fel, IBM Corp. 


-— = 
= 
om | 
<—c 
ZL 

& 
— 

_—™ 
= | 
a 

fa 

[— ] 

= 

f= be) 

Fo 

Le | 
| 


nis 
SS 
‘) yee) 


ih Aha i eth 
AAR 


REND SUAS SS 


: 
a 


DYNAMIC DATA EXCHANGE for 
OS/2 PROGRAMMERS 


VNR’s OS/2 SERIES 


Using Workplace OS/2: Power User’s Guide to IBM OS/2 Version 2.1 by Lori 
Brown and Jeff Howard 

OS/2 2.X Notebook: Best of IBM OS/2 Developer Edited by Dick Conklin 
Objects for OS/2 by Scott Danforth, Paul Koenen, and Bruce Tate 

The Cobol Presentation Manager Programming Guide by David M. Dill 
OS/2 Presentation Manager Mentor by Michael Drapkin 

OS/2 and Netware Programming: Using the Netware Client API for C by Lori 
Gauthier 

OS/2 2.1 REXX HANDBOOK: Basics, Applications, and Tips by Hallet German 


Developing C and C++ Software in the OS/2 Environment by Mitra Gopaul 


OS/2 2.1 Application Programmer’s Guide by Tody Kelly, Craig Swearingen, 
Dawn Bezviner, and Theodore Shrader 

Learning to Program OS/2 2.0 Presentation Manager By Example: Putting 
the Pieces Together by Stephen A. Knight 

Object-Oriented Programming Using SOM and DSOM by Christina Lau 
OS/2 C++ Class Library: Power GUI Programming with C Set ++ Interface 
Class Library by Kevin Leong, Bill Law, Bob Love, Hiroshi Tsuji, Bruce Olson 
Now That I Have OS/2 2.1 On My Computer — What Do I Do Next?, Second 
Edition by Steven Levenson 

The Shell Collection: OS/2 2.X Utilities by Steven Levenson 

The GUI-OOUI War — Windows vs. OS/2: The Designer’s Guide to Human- 
Computer Interfaces by Theo Mandel 

Writing OS/2 2.1 Device Drivers in C, Second Edition by Steven Mastrianni 
Developing Multimedia Applications Under OS/2 by Brad Noe, Marcelo Lopez, 
and Bill Lawton 

Client/Server Survival Guide with OS/2 by Robert Orfali and Dan Harkey 
Client/Server Programming with OS/2 2.1, Third Edition by Robert Orfali and 
Dan Harkey 

Dynamic Data Exchange for OS/2 by Glenn Puchtel 

OS/2 LAN Server: The Do-It-Yourselfer’s Guide to Painfree Networking by 
Pat Scherer 

The OS/2 2.1 Corporate Programmer’s Handbook by Nora Scholin, Marty 
Sullivan, and Robin Scragg 

WIN Functions OS/2 Quick Reference Library, Vol 1 by Nora Scholin 
Message Functions OS/2 Quick Reference Library, Vol 2 by Nora Scholin 
Workplace Shell Functions OS/2 Quick Reference Library, Vol 3 by Nora 
Scholin 

GPI Functions OS/2 Quick Reference Library, Vol 4 by Nora Scholin 

DOS Functions OS/2 Quick Reference Library, Vol 5 by Nora scholin 

Misc. Functions OS/2 Quick Reference Library, Vol 6 by Nora Scholin 
Running Windows Applications in OS/2: A Power User’s Guide by Jean 
Shortley, Ayodele Anise, and Teresa Beck 


OS/2 Remote Communications: Asynchronous to Synchronous—Tip and Tech- 


niques by Ken Stonecipher 

Secrets of the OS/2 Masters by Marty Sullivan 

Comprehensive Database Performance For OS/2 2.0’s Extended Services by 
Bruce Tate, Tim Malkemus, and Terry Gray 

Lotus Notes Release 3 in the OS/2 Environment by Tony Walsh 

OS/2 Presentation Manager GPI, Second Edition by Graham C.E. Winn 

The OS/2 Handbook: Applications, Integration, and Optimization, Second 
Edition by William H. Zack 


DYNAMIC DATA EXCHANGE for 
OS /2 PROGRAMMERS 


Glenn Puchtel 


VAN NOSTRAND REINHOLD 


I@)P A Division of International Thomson Publishing Inc. 


New York e Albany e Bonn e Boston e Detroit e London e Madrid « ee 
Mexico City ¢ Paris e San Francisco ¢ Singapore * Tokyo « Toront 


DISCLAIMER 

This book and software are provided “as is.” The implied warranties of merchantability and fitness 
for a particular purpose are expressly disclaimed. This book and software may contain programs 
that are furnished as examples. These examples have not been thoroughly tested under all condi- 
tions. Therefore, the reliability, serviceability, or function of any program or program code herein is 
not guaranteed. The authors and publishers shall not be liable in any event for any loss or damages 
in connection with, or arising out of, use of this book or the companion diskette. 


OS/2 Accredited logo is a trademark of IBM Corp. and is used by Van Nostrand Reinhold under li- 
cense. “Dynamic Data Exchange for OS/2 Programmers” is independently published by Van Nos- 
trand Reinhold. IBM Corp. is not responsible in any way for the contents of this publication. 


Van Nostrand Reinhold is an accredited member of the IBM Independent Vendor League. 


Copyright © 1995 by Van Nostrand Reinhold 
(TP A division of International Thomson Publishing Inc. 
The ITP logo is a trademark under license 


Printed in the United States of America 
For more information, contact: 


Van Nostrand Reinhold International Thomson Publishing GmbH 
115 Fifth Avenue Konigswinterer Strasse 418 
New York, NY 10003 53227 Bonn 
Germany 
International Thomson Publishing Europe International Thomson Publishing Asia 
Berkshire House 168-173 221 Henderson Road 
High Holborn Henderson Building 
London WC1V 7AA Singapore 0315 
England 
Thomas Nelson Australia International Thomson Publishing Japan 
102 Dodds Street Hirakawacho Kyowa Building, 3F 
South Melbourne, 3205 2-2-1 Hirakawa-cho 
Victoria, Australia Chiyoda-ku, 102 Tokyo 
Japan 
Nelson Canada International Thomson Editores 
1120 Birchmount Road Campos Eliseos 385, Piso 7 
Scarborough, Ontario Col. Polanco 
Canada, M1K 5G4 11560 Mexico D.F. Mexico 


All rights reserved. No part of this work covered by the copyright hereon may 
be reproduced or used in any form or by any means—graphic, electronic, or 
mechanical, including photocopying, recording, taping, or information storage 
and retrieval systems—without the written permission of the publisher. 


12345678910 QEBFF 01 00 99 98 97 96 95 94 
Library of Congress Cataloging-in-Publication Data 


Puchtel, Glenn T. 
Dynamic data exchange for OS/2 programmers / [Glenn T. Puchtel]. 
p. m. 
Includes bibliographical references and index. 
ISBN 0-442-01949-1 
1. OS/2 Computer file) 2. Data structures (Computer science) 


I. Title. 
QA76.76.063P82 1994 
005.7 ' 1265—dc20 94—31803 


CIP 


Contents 


Chapter 1 


Chapter 2 


Chapter 3 


TRADEMARKS _ xi 

CONVENTIONS USED IN THIS BOOK - xiii 
HOW TO USE THIS BOOK ~ xvi 

FOREWORD - xxi 

PREFACE — xxiii 

LIST OF ILLUSTRATIONS AND TABLES = xxv 


The DDE Protocol 1 

INTRODUCTION 1 

OVERVIEW 1 

AUSER’S VIEWPOINT 2 

A DEVELOPER’S VIEWPOINT 3 

AN ANALOGY OF THE DDE PROTOCOL 4 


The DDE Initiation Process 9 


STRUCTURE DEFINITION — 11 
NATIONAL LANGUAGE SUPPORT (NLS) 31 


The DDE DatalItem 35 


ANATOMY OF A DDE DATAITEM — 35 
DDE DATA FORMATS — 36 


vi CONTENTS 


Chapter 4 DDE Transactions 43 


DDE RESPONSES = 46 

MESSAGE SYNCHRONIZATION = 49 
REQUEST 50 

ADVISE 58 

UNADVISE 72 

POKE = 83 

EXECUTE 86 

TERMINATE 88 


Chapter 5 The System Topic 93 


Chapter 6 Differences Between PM and Windows DDE 97 


ATOM MANAGEMENT 98 
MEMORY MANAGEMENT 98 
STATUS FLAGS 98 
MESSAGES and STRUCTURES 98 
WM_DDE_ACK 99 
WM_DDE_ADVISE 100 
WM_DDE_DATA 100 
WM_DDE_EXECUTE 101 
WM_DDE_INITIATE 101 
WM_DDE_INITIATEACK 102 
WM_DDE_POKE 102 


WM_DDE_REQUEST, WM_DDE_TERMINATE, and 
WM_DDE_UNADVISE 102 


Appendix A DDE Structures’ 103 


CONVCONTEXT = 108 
CPTEXT 105 
DDEINIT = 106 
DDESTRUCT 108 
MFP 110 


Appendix B DDE Messages 113 


WM_DDE_ACK § 118 
WM_DDE_ADVISE 116 


Appendix C 


Appendix D 


Appexdix E 


Appendix F 


Appendix G 


CONTENTS 


WM_DDE_DATA 118 
WM_DDE_EXECUTE = 120 
WM_DDE_INITIATE = 122 
WM_DDE_INITIATEACK = 123 
WM_DDE_POKE 124 
WM_DDE_REQUEST 126 
WM_DDE_TERMINATE = 127 
WM_DDE_UNADVISE 128 


DDE Functions 131 


DDE Macros_ 139 


DDEI_PCONVCONTEXT = 139 
DDES_PABDATA — 140 
DDES_PSZITEMNAME — 140 


DDE Status Flags 141 


DDE_FACK 142 
DDE_FACKREQ_ 142 
DDE_FAPPSTATUS = 142 
DDE_FBUSY = _ 143 
DDE_FNODATA — 143 
DDE_FRESERVED = 143 
DDE_FRESPONSE = 144 
DDE_NOTPROCESSED 144 


DDE Library 145 
Frequently-asked DDE Questions 167 


Index 171 


vii 


viii 


Trademarks 


The following terms used in this publication are trademarks or registered 
trademarks of International Business Machines Corporation in the 
U.S.A and/or other countries: 


IBM, C Set/2, OS/2, and Presentation Manager 


The following terms used in this publication are trademarks or regis- 
tered trademarks of other companies, as follows: 


9 is a trademark of Windows 3.1 from Microsoft Corporation. 
Windows is a trademark of Microsoft Corporation. 


Conventions Used in This Book 


The following typographical conventions are used throughout this book: 


Bold Text 


Italic Text 


CAPITALS 


monospace 


Indicates a word is a function name, data type, or other 
fixed part of the OS/2 DDE Application Programming In- 
terface. For example, WinDdelnitiate is a DDE-specific 
function and DDEINIT is a DDE-specific data structure. 


Indicates a word that is a variable or formal parameter 
name; for example, pszTopicName indicates either a vari- 
able or a parameter name. Function parameters in APIs 
are italicized to indicate that a variable name can be used. 
Also, italic text can introduce a term related to the current 
subject. 


Indicates CONSTANTS; for example, WM_DDE_INITI- 
ATE. Most constants are defined in the PMWIN.H header 
file. 


Indicates source code and syntax; for example: 


BOOL fResult = WinDdeRespond 
( hwndClient 
, hwndServer 
, “ServerName” 
, “TopicName” 

» NULL 

jiceg 


Indicates a note relating to the Windows implementation 
of DDE. 
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CONVENTIONS USED IN THIS BOOK 


Hungarian notation is used in the code fragments throughout this 
book. Hungarian notation is a convention used to name variables or 
formal parameters of a function prototype and definition. The name 
Hungarian comes from the nationality of its original developer, Charles 
Simonyi. At first, the convention may be confusing; however, once you 
become familiar with the convention you will find that the clarity of your 
applications is enhanced. 

Hungarian notation is mainly used to avoid misuse of variables and 
parameters in an application program. Hungarian notation is not re- 
quired, nor is it related to DDE; its complete definition is beyond the 
scope of this book. It is briefly presented here to give the reader a better 
understanding of its usage. 

Variable names consist of three elements: prefix, base type, and 
qualifier. Not all elements are present in all variables, and only the base 
type is required. Base types are not the same as data types in a 
programming language; rather, they are application-dependent. For 
example, in hwndClient the prefix is h, the base type is wnd, and the 
qualifier is Client. It is also possible to have more than one prefix; for 
example, offabData has two prefixes, off (offset to) and a (array of). 

The following is a partial list of variable and parameter name-prefixes 
used in this book and its example programs: 


Prefix Usage 
a Anarrayof...;for example, abData is an array of bytes. 
c count of... ; for example, cbData is a count of bytes. 
f flag; for example, fResult is a Boolean flag indicating a 
success or failure of a function. 
h handle; for example, hwnd is a handle to a window. 


off offset to... ; for example, offszltemName is an offset to a 
NULL terminated ASCII string. 
p pointer to...; for example, pDdeStruct is a pointer to a 
DDESTRUCT. 


sz NULL (0x00) terminated ASCII string; for example, 
szIltemName is a NULL terminated ASCII string that 
represents the name of a DDE item. 

ul unsigned long; for example, ulMsg. 

us unsigned short; for example, wsFormat is a Format iden- 
tifier the size of an unsigned short. 


Assumptions 


How to Use This Book 


This book is designed to be the definitive guide to the OS/2 Dynamic Data 
Exchange (DDE) protocol. It was written to serve as a reference guide 
for experienced Presentation Manager programmers incorporating DDE 
functionality into their applications. Both an overview and detailed 
discussions about the DDE protocol is contained in this book, along with 
specifications for all DDE messages, structures, and APIs. 

Code fragments shown in this book were extracted directly from the 
example programs included on the companion diskette accompanying it; 
these code fragments illustrate working code from working applications 
rather than fragmented pieces of unrelated functions. Listings are used 
to illustrate the topic being discussed; however, since these listings 
were extracted from sample code, they may also contain statements not 
directly related to the current topic. See “Example Programs” below, for 
further information regarding the design of these programs on diskette 
accompanying this book.) 


For developers writing DDE applications, it is assumed that readers 
understand basic OS/2 and Presentation Manager concepts, including, 
but not exclusive to, the following: 


= Messages 
a Message Queues 
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Example Programs 


WC_DdeConv 


WC_DdeTopic 


x Atom Management (both Integer and String Atoms) 
a OS/2 Shared Memory Management 
a C Programming Language (to understand the examples only) 


The example programs contained on diskette accompanying this book 
were compiled using the IBM C/C++ 2.0 compiler. Further information 
regarding the example programs can be found in the README. TXT file 
on the companion diskette. 

The two example programs (a client and a server) were developed 
to illustrate how the DDE protocol could be implemented in actual 
working applications. The intent was not only to show DDE, but to 
create useful applications that could be used to communicate with, 
and test, any DDE-capable application. Wherever possible existing ca- 
pabilities of Presentation Manager were used. For example, rather 
than creating functions to handle link-lists of data, the hierarchial 
architecture of Presentation Manager windows was used to maintain 
these lists and “window” instance-data in order to store the data. In 
addition, use of windows allowed for the creation of classes that im- 
plemented specific DDE behavior (by processing class information a 
window procedure). 

The following window-classes were developed to implement DDE 
behavior—both the client and server example applications use these 
classes and are referenced in the code fragments throughout this book. 


This class handles DDE conversations. One window of this class is 
created for each conversation the client or the server are engaged in. In 
this class, specific information regarding a conversation link is main- 
tained, such as: 


The current state of the conversation 

The window handle of its conversation partner 

The application and topic name-strings of the conversation 
Conversation context information (as specified in a 
CONVCONTEXT structure) 


This class handles DDE topics. One window of this class-style is created 
for each topic a server application supports. Also, the client application 
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creates one window of this class-style for each topic it has engaged into 
a conversation link. In this class, specific information regarding a topic 
is maintained, such as: 


a Where to find the topic name-string, and the name-strings of 
each item supported in the topic (The example programs use 
a WC_MENU class window to maintain this information.) 

» Acount of how many conversations this topic is engaged in 


WC_Ddeltem 


This class handles DDE items. One window of this class-style is created 
for each item supported by a WC_DdeTopic class window. In this class, 
specific information regarding a DDE item is maintained, such as: 


=» A window handle of a WC_MENU class window (The item 
name-string associated with this item is stored in a 
WC_MENU class window. ) 

=» Ahandle to an item-specific object (For example, a pointer to 
text, time, or the handle of another WC_MENU class win- 
dow—to support items containing a list of string.) 


WC_DdeAdvise 


This class handles permanent DDE data-links. One window of this 
class-style is created for each DDE format and conversation pair re- 
quested by a WM_DDE_ADVISE transaction. In this class, specific 
information regarding a data-link is maintained, such as: 


# The DDE status flags of the original WM DDE ADVISE 
request 

# Whether or nota WM_DDE_ACK message is pending (in the 
case where DDE_FACKREQ was specified in the original 
request) 

» The window handle of the original requesting (client) appli- 
cation (This window handle is used to post WM_DDE_DATA 
messages. ) 


Figure I-1 shows how the example client and server applications 
incorporate the above-mentioned window-classes to implement DDE 
functionality. This figure should be referred to when examining the 
examples and code fragments. 
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Foreword 


When IBM introduced OS/2 version 2 in 1992, it quickly became the 
leading 32-bit multitasking operating system for personal computers. 

Today, OS/2 continues to build on its momentum, winning a number 
of industry awards and gaining more and more customer acceptance. 

When users talk about OS/2, they usually talk about its seamless 
support for DOS, Windows, and OS/2 applications, its ease-of-use fea- 
tures like the object-oriented, graphical user interface, and its broad 
range of hardware support. 

But there’s much more inside OS/2. One example is Dynamic Data 
Exchange (DDE), the subject of this book. It’s one of the features of the 
OS/2 that makes it so powerful as an “integrating platform.” DDE allows 
programs to exchange data dynamically as an application is running, 
and it doesn’t matter if the applications are Windows or OS/2, or a 
combination. Glenn Puchtel, an engineer on the OS/2 development team, 
provides the programmer with “everything you wanted to know about 
DDE, but were afraid to ask.” 

I commend him for this outstanding guide through the world of 
Dynamic Data Exchange. 


Lois A. Dimpfel 

Director, Personal Operating Systems 

Personal Software Division Programming Center 
IBM Boca Raton 
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Preface 


Dynamic Data Exchange (DDE) continues to be a little-known area of 
the OS/2 operating system. Developers of DDE applications have been 
hindered by incomplete documentation and inadequate programming 
examples. Even today, no official definition of the protocol exists and 
example programs are scarce. As a result, many areas of the DDE 
protocol remain vague and are subject to interpretation. Subsequently, 
DDE applications are often incompatible or flawed. 

During my involvement with DDE, I have observed many diverse 
usages of the protocol in applications. Although most applications ad- 
hered to the basics of the protocol, many applications varied in the more 
subtle areas. When trying to validate these variations against a reliable 
document or a sample program, I found that the available documents 
were not always adequate or were incorrect, and complete programming 
examples did not exist. 

All this lead to the realization that there was a need for a book that 
definitively defines the DDE protocol, clears up the vague areas, and 
provides complete programming examples. Hopefully, you will find that 
this book and its supporting examples meet this objective. 
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INTRODUCTION 


OVERVIEW 


The DDE Protocol 


This chapter introduces the Dynamic Data Exchange (DDE) protocol by 
giving an overview of the protocol, examining the protocol from the 
end-user’s and application developer’s viewpoint, and, finally, illustrat- 
ing the concept of the protocol with a brief analogy. 


DDE first appeared in 1986 with the release of Windows version 1.03. 
In 1987, version 1.2 of the OS/2 operating system was released. This 
version of the OS/2 operating system contained a migrated implemen- 
tation of the Windows DDE protocol. The result of the migration made 
the OS/2 DDE implementation more consistent than its Windows coun- 
terpart; capabilities that now exist in the OS/2 version are undefined or 
unsupported in Windows. A summary of these differences is included in 
Chapter 6, “Differences Between PM and Windows DDE.” 


DDE allows data exchange between applications, even applications 
from different vendors. By using DDE, applications are shielded from 
the operating details of another application. As long as both applications 
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agree on the type of data being exchanged, they can share data. For 
example, a spreadsheet application may share a graph with a word- 
processor application. The word-processor application need only know 
that the data is a graph and not how it was generated. 

Exchanging data is not as simple as accessing each other’s resources. 
In a multiprocess operating system such as OS/2, resources in one appli- 
cation are protected from being accessed by another application. Mem- 
ory protection, providing security and reliability, is one of the major 
strengths of the OS/2 operating system. However, this same memory- 
protection scheme creates an obstacle when applications truly need or 
want to share their data. 

To facilitate this need, Inter Process Communication (IPC) mecha- 
nisms are provided by the OS/2 operating system. For example, an 
application can use shared memory, queues, or pipes. Each of these IPC 
methods requires each application to be aware of the method being used 
and to have specific knowledge to access the data. 

In a windowed environment such as Presentation Manager (PM) or 
Windows, the primary method of IPC is passing messages. The same 
memory protection of the underlying operating system still applies to 
data passed in messages. If one application needs to give data to an- 
other, it must allocate a shared memory object and give that memory 
object to the receiving process. 


A USER’S VIEWPOINT 


To the user, DDE typically appears as the ability to import or export 
data between applications. It usually differs from the copy/paste opera- 
tions of the clipboard in which user interaction is required. The clip- 
board is used for one-time data transfer and is almost always 
user-initiated. Like the clipboard, DDE can be used to perform a one- 
time data transfer. Unlike the clipboard, DDE applications can ex- 
change data on an ongoing basis without user intervention. 

For example, consider the scenario of an application attached to some 
sort of information service such as the stock exchange. In this example, 
an application would be notified automatically whenever a stock price 
changed. Users no longer have to be burdened with querying the data 
themselves; it comes to them automatically! Most users are unaware 
that an application is using DDE. To them it is simply a feature of the 
application. Other uses for DDE include: the monitoring of real-time 
equipment or the creation of complex documents that may gather data 
from other applications that are continuously changing. 
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A DEVELOPER’S VIEWPOINT 


To an application developer, DDE is a client/server-based protocol con- 
sisting of a set of messages, macros, and data structures. A set of 
Application Programming Interfaces (APIs) is available that operate on 
these defined elements along guidelines on how and when to use them. 
Client/server implies a relationship between two applications where the 
server is the provider of services and the client is the consumer of those 
services. Services provided by a server can be either data or the ability 
to execute commands on behalf of a client. A server can provide services 
to one or more clients, and a client can request services from one or more 
servers. Also, an application can be a client and a server; that is, it can 
request services from a server while providing services to clients. 

Typically, client/server protocols use messages to deliver requests and 
replies. A client/server protocol works well with PM since PM is a 
message-based system. DDE messages are dispatched just like any 
other PM message. 

Figure 1-1 illustrates message-dispatching logic common to all PM 
applications. 

Typically, this message loop exists in the main function of an applica- 
tion (more accurately, a message loop exists in each thread of an appli- 


Message Queue Message Loop Window Procedure 


WM_DDE_* 


WinGetMsg() 


< 


WM_DDE_* 
WinDispatchMsg() 


Switch(msg) 


Case : WM_DDE_* 


} 


Figure 1-1. Message-dispatching WinGetMsg scans the applications message queue 
looking for messages (a). If a message exists, it is removed from the queue (b) and placed 
into an applications memory (QMSG) structure (c). The message is then dispatched to its 
corresponding window procedure (d), where it is processed. After processing the message, 
the window procedure returns back to the dispatcher (e). This sequence is repeated for the 
next message (f) until a WM_QUIT message is placed into the message queue, at which 
time the loop will be exited. 
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cation that created a PM Message Queue). From this loop all messages 
are dispatched to a window procedure associated with the window 
handle specified in the message. DDE messages are dispatched from 
this message loop just like any other message. 

DDE is often described as the exchange of data between two ap- 
plications. Actually, the exchange of data occurs between two windows. 
Since the DDE protocol is based on messages being dispatched to a 
window (technically its window procedure), DDE is not available to 
applications that do not have window procedures. In order for data 
exchange to occur, each application must be aware of one another’s 
window handles. Through the predefined set of PM APIs and mes- 
sages, one application can obtain the window handle of another ap- 
plication and establish a conversation (often called a link) with one 
another. Once a link is established, participants engage in the ex- 
change of DDE transactions until one of the participants terminates 
the link. For each transaction, there are guidelines on how to perform 
the transaction and what the responsibilities of each participant are 
in the transaction. 


AN ANALOGY OF THE DDE PROTOCOL 


As with any type of conversation, be it between applications or humans, 
someone must initiate it. In DDE it is the client application that must 
initiate the conversation. The following analogy will help make this 
initiation process easier to understand. 

Let’s say you just walked into a crowded room and you want to start 
a conversation with your friend John. You don’t know if he is there, so 
you shout, “Hey, John!” If he is in the room, he may answer; however, 
anyone else with that name will also answer. At this point you shout, 
“Hey, John Doe!” Hopefully, there is only one John Doe. If there is and 
he answers, then you have initiated your conversation. If John Doe is 
not in the room, you will get no answer at all. However, he might be in 
the room, but busy and unable to answer right away. And, if there is 
more than one John Doe, both will answer. Now what? This last scenario 
is easily handled by humans, but in DDE there is no way to distinguish 
between identical responses from different sources. This is just one of 
deficiencies you will discover in DDE. 

DDE conversations are initiated by a client application and are based 
on a two-tier hierarchy similar to your first and last name. In DDE 
these are called the “Application” and “Topic” names. As in the analogy, 
you can specify one, both, or neither. The “neither” scenario was not 


THE DDE PROTOCOL 5 


discussed, but it would go like this: “Hey you!” At this point you may get 
many answers, not all of them friendly. 

An application name is usually the name of the executable program, 
for example, “MyApp”. A topic is typically the name of a file in a 
spreadsheet application or a document in a word-processor application. 
During the initiation process a server determines if it can satisfy the 
client’s request. If the server cannot satisfy the request, it does not 
respond. If it can satisfy the request, the server will create a new 
window and include the handle of this newly-created window in its 
response. A server responds once for each topic it is willing to support. 
For each response, a server must provide a unique window handle; this 
guarantees that each and every window handle pair identifying a con- 
versation link is unique. 

In addition to being a requirement, there are several benefits in 
creating a new window for each response: 


# An application can identify a particular conversation link 
simply by the window handle (in PM, a window handle is 
guaranteed to be unique). 

s Standard PM API calls can be used to maintain and control 
conversation links (e.g., WinEnumerateWindow). This 
frees an application developer from having to develop a 
special structure to maintain this information, such as 
linked lists. 

= A window can contain instance data; that is, information can 
be on a per-window (or in this case a per-conversation) basis. 
This simplifies the programming logic of multiple conversa- 
tions. Typically, developers create these windows as invisible 
since their main purpose is to handle a DDE conversation 
link rather than to display information. 


Once a DDE conversation has been established, client applications 
can request services from a server in what are known as DDE transac- 
tions. In DDE, all transactions are one-way; a client always issues the 
request and a server responds (the only exception to this rule is the 
Terminate transaction). At this point, the client must be specific in what 
it wants from the server; it does so by providing the “data item” name 
of a service. A data item is often referred to as the third and final part 
of a three-part hierarchy (the application and topic names being part 
one and two respectively). Here again, a quick return to our analogy will 
help depict the DDE transaction process. 

Let’s assume that you and John have engaged in a conversation but 
are currently involved in separate activities. For example, John is 
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watching a baseball game, and you are playing cards in the other room. 
The topic of conversation is baseball, so, from time to time you ask John, 
“What’s the score?” and John responds, “3 to 1.” A little later you ask 
John again, “What’s the score?” and John responds. You can repeat this 
as many times as you desire, and John, being the good friend that he is, 
continues to respond to your requests. Of course, if John is busy he will 
not be able to give you the score. 

As you can tell, this can be a little tedious (and a little annoying). 
Another way would be to ask John to tell you the score whenever it 


Client Server 


WinDdelnitiate ( ) 


WinDdeRespond ( ) 


WinDdePostMsg ( ) WM_DDE_REQUEST 


WinDdePostMsg() | |WM_DDE REQUEST 


WM_DDE_DATA WinDdePostMsg ( ) 


WindePoste 


WinDdePostMsg ( ) 


WM_DDE_TERMINATE WinDdePostMsg ( ) 


Figure 1-2. Message Flow: Overall 
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changes. This way you don’t have to keep bothering John as the score 
may not have changed since the last time you asked. 

In this analogy the baseball score was the particular item of interest 
in your conversation. In DDE, a “data item” is some type of information 
or possibly a set of commands a client wants the server to perform on 
its behalf. Typically, items are a group of cells in a spreadsheet, a 
paragraph in a document, or some type of identifiable object such as a 
graph or chart. Once an item has been defined, a name must be associ- 
ated with it. Usually this is done by the user of the application. For 
example, a user highlights a block of text and associates a name with 
it. The method in which a name is associated is application-specific. 

A conversation continues until one of the participants terminates it. 
A conversation can be terminated by either participant at any time. This 
is the only exception to the one-way rule, in which a server can issue the 
request and a client must respond. Notice that I stated a client must 
respond. A client or a server cannot respond with a negative acknow- 
ledgement; it must handle the termination request. In our analogy this 
would be either person leaving and saying good-bye. 

Although this analogy is somewhat whimsical, it illustrates that DDE 
communications are not unlike conversations that two people might 
have. A condensed summary of a DDE conversation is illustrated in 
Figure 1-2. 


2 


The DDE Initiation Process 


Before DDE transactions can occur between applications, a client appli- 
cation must establish a conversation link with a server application. The 
process of establishing a conversation link is called the DDE initiation 
process and is illustrated in Figure 2-1. 

A client begins the initiation process by issuing a WinDdelInitiate 
API, specifying the desired server and topic name with which it wishes 
to establish a conversation link. Listing 2-1 illustrates how a client 


Client Server 


Is there anyone 
who can talk about... 


WinDdelnitiate ( ) WM_DDE INITIATE Yes, I can. 


Ok, let's talk. M_DDE_INITIATEAC WinDdeRespond ( ) 


Figure 2-1. DDE Initiate Message Flow 


/* 


K* 


ay 


/* 


xK* 


a 


/* 


K* 


a 


APTRET ApiRet; 
USHORT cbReturned; 


BOOL FResult = FALSE 

HWND hwndConv = hwndClient; 

CHAR SZAppName LMAX_NAME_LENGTH] = “DDEServer”; 

CHAR SZTopicName [LMAX_NAME_LENGTH] = SZDDESYS_TOPIC; 

Query current country and code page information of client application... 

CtryCode.country = OL; /* Query default system country code ay 

CtryCode.codepage = OL; /* Query current process codepage at | 

ApiRet = DosQueryCtrylInfo /* Query country-dependent information wf 
( sizeof (CtryInfo) /* Size in bytes to hold returned info wf 
, &CtryCode /* specifies query criteria a 
, &CtryInfo /* buffer to receive queried information */ 
, &cbReturned /* size (in bytes) of returned information*/ 
Ms 


setup the Client’s default conversation context structure. These values 
define the context for NLS conversations. 


ConvContext.cb = sizeof (CONVCONTEXT); 
ConvContext.fsContext = QOL; 
ConvContext.idCountry = LUPylite.cauntry: 


ConvContext.usCodepage = WinQueryCp (hmq); 
ConvContext.usLangID OL; 
ConvContext.usSubLangID = OL; 


Create a “WC_DdeConv” class window to support conversation link... 


hwndConv = DdeCreateConvWindow /* Create a conversation link window a 
( hwndClient /* client window handle =f 
, NULLHANDLE /* partner window handle (not applicable) */ 
, szAppName /* desired application name oy 
, pSzlopic /* desired topic at 
, &ConvContext /* conversation context structure ae 
); 


If “WC _DdeConv” class window successfully created... 


if (hwndConv) /* if conversation window was created my 
fResult = WinDdelInitiate /* broadcast WM_DDE_INITIATE message wf 

( hwndConyv /* requesting window handle ai 

, pszAppName /* desired application name af 

, pszlapic /* desired topic ay 

, &ConvContext /* conversation context structure ca 


Listing 2-1. Client: DDE Initiate Request 


Note: The SZDDESYS_TOPIC name-string is defined in the PMWIN.H header file as “System.” 
For further information regarding the System topic, refer to Chapter 5, “The System Topic.” 
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application could issue a DDE Initiate request for a server named 
“DDEServer” that supports the “System” topic. 

As shown in Listing 2-1, the client application first obtains country and 
codepage information to identify its conversation context [see “National 
Language Support (NLS)” in this chapter]. Next, a window is created to 
support the new conversation link. Finally, the Initiate request is issued. 

The WinDdelnitiate API creates a memory object from shared mem- 
ory containing a DDEINIT structure, as shown in Figure 2-2, fills in this 
structure with the parameters specified in the API call, and then sends a 
WM_DDE_INITIATE message to all top-level frame windows. (For a 
detailed description of each element of the DDEINIT structure, see 
“DDEINIT” in Appendix A.) Even though an application does not have to 
create the DDEINIT structure, it is important to understand its con- 
tents so that an application can extract and interpret them correctly. 


STRUCTURE DEFINITION 


typedef struct _DDEINIT 
ULONG CD: /* size of memory object (in bytes) st 
Pod pszAppName; /* pointer to null (0x00) terminated ASCII text string */ 
PS$Z pszlopic; /* pointer to null (0x00) terminated ASCII text string */ 
ULONG offConvContext; /* offset (in bytes) to start of ConvContext structure */ 
DDEINIT; 


Each top-level frame window receives its own copy of the memory ob- 
ject containing a DDEINIT structure. The address of this memory object 
is passed in message parameter two (mp2) of the WM_DDE_INITIATE 
message and is dispatched to the frames window procedure. 


Myth: An application must sub-class a frame window to receive 
the WM_DDE_INITIATE and WM_DDE_INITIATEACK 
message. 

Fact: A frame window procedure sends all unsupported mes- 
sages (including the WM_DDE_INITIATE and WM_DDE - 
INITIATEACK messages) to a client window, if one exists; 


offConvContext 


Figure 2-2. DDEINIT Structure 
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otherwise, it calls the WinDefWindowProc default window 
procedure. 


The following pseudo code illustrates frame message processing: 


MRESULT 

EXPENTRY  FrameWindowProc 
( 

HWND hwnd 
ULONG ulMsglId 
MPARAM mp1 

MPARAM mp2 


MRESULT MResult; 
Switch (ulMsgId) 
{ 


(other case: statements) 


default: 
if Lclient window exists...] 
{ 
MResult 
} 
else 
{ 
MResult = WinDefWindowProc (hwnd, ulMsglId, mpl, mp2); 
} 
return (MResult); 


WinSendMsg (hwndClient, ulMsgId, mpl, mp2); 


MRESULT 
EXPENTRY ClientWindowProc 
( HWND hwnd 

ULONG ulMsgld 


MPARAM mp1 
MPARAM mp2 


PDDEINIT pDdelnit = (PDDEINIT) PVOIDFROMMP (mp2); 
[rest of window procedure] 


If the server is willing to respond to the initiation request, it issues a 
WinDdeRespond API. This results in an Initiate acknowledgement 
(WM_DDE_INITIATEACK) message being sent back to the requesting 
application (see Figure 2-4). The complete process is illustrated in 
Figure 2-3. 
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Client PM 
oo ( ) 


WinDdelnitiate ( ) (a) 


ae | 


DDEINIT >_> DDEINIT 


WinSend ( ) WinSend ( ) 


| 4 > 
(c Server | 


eS Ss ba a eee 
~ 


WM_DDE INITIATE 
"aa () 


WM_DDE_INITIATEACK : WinDdeRespond ( ) 


Return (MRESULT) 


Figure 2-3. Anatomy of the WinDdelnitiate API A DDE client application is- 
sues a WinDdelnitiate API (a), which allocates a shared memory object large enough 
to contain a DDEINIT structure and initializes the structure with the parameters 
specified in the API call (b). Each top-level frame window is sent a WM_DDE_INIT 
ATE message (c). If the application is DDE-capable, it responds by issuing a WinD- 
deRespond API (d), which sends a WM_DDE_INITIATEACK message back to the 
originating application (e). The client application then returns a value indicating 
success or failure (f). At this point, the server application must free the (DDEINIT) 
memory object associated with the WM_DDE_INITIATE message (g) and return from 
processing the WM_DDE_INITIATE message (h). The next top-level frame window is 
identified and the process is repeated (i). After each top-level frame window has been 
sent a WM_DDE_INITIATE message, control is returned to the application issuing 
the WinDdelInitiate API ( j). 


Note: A top-level frame window is any window created using the CS_FRAME class 
style and whose parent is the desktop (HWND_DESKTOP). Also, the return code from 
the WinDdelInitiate API should not be confused with the value returned by a server 
application when it processed the corresponding WM_DDE_INITIATE message. (For 
further information see “WinDdelnitiate” in Appendix C.) 
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The DDE initiation process is synchronous and serialized. That is, the 
entire initiation process completes before the WinDdelnitiate API 
returns to its caller. This is an important point, key to understanding 
this process. 

Synchronization and serialization allows a client application to make 
the following assumptions: 


# Any and all WM_DDE_INITIATEACK messages received by 
the client are a direct result of issuing the WinDdelInitiate 
API. 

=» All server applications that are capable of responding have 
responded. 


Typically, a client application determines its state before and after 
issuing the WinDdelInitiate API. This can be as simple as setting a 
Boolean flag to FALSE before issuing the API; then, upon receiving a 
(WM_DDE_INITIATEACK) acknowledgement message, the client 
could set this flag to TRUE. Finally, after returning from the API, the 
client checks this flag for TRUE or FALSE and determines success or 
failure accordingly. Notification Gf any) of success or failure of this 
process is application-specific. 

As stated, DDE conversations are based on a application/topic pair, 
implying that a client application must know the names of both the 
server and topic at the time of the initiation request. What if the client 
application does not know the exact names? Or, the server supports 
many topics? To allow client applications to obtain names of unknown 
servers and topics, the DDE protocol supports a technique known as 
wild-cards. 

A wild-card is a zero-length string and may be specified for either the 
application name-string, the topic name-string, or both. A wild-card 
should be interpreted as if the user had said, “I don’t care.” If specified 
as the application name-string, any DDE server may respond. If speci- 
fied as the topic name-string, each responding server should respond 
once for each topic it is willing to support. By using wild-cards a client 
can obtain the names of all active DDE servers, or a list of topics 
currently supported by a DDE server. 

As an alternative to wild-cards, DDE server applications are en- 
couraged to support the System topic and its associated 
SZDDESYS_ITEM_TOPICS item. In doing so, client applications can 
not only obtain a current list of supported topics but issue initiate 
requests with a known topic name-string. This greatly reduces the 
number of WM_DDE_INITIATEACK messages generated during the 
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initiate process. Remember, if a wild-card is specified for the topic 
name-string, the server will respond (and generate a WM_DDE_IN- 
ITIATEACK message) for each topic it supports. 


3—) Many DDE server applications written for Microsoft Win- 
dows do not support the System topic. Moreover, a well-be- 
haved DDE application should never assume that another 
application has implemented the protocol correctly. There- 
fore, a DDE server application should always honor an initia- 
tion request that specifies wild-cards in addition to 
supporting the System topic. Some so-called new DDE appli- 
cations incorrectly assume that it need only support the 
SZDDESYS_ITEM_TOPIC item. 


If a server chooses to respond, it acknowledges the request by calling 
the WinDdeRespond API once for each topic it is acknowledging. 
The WinDdeRespond API will create a DDEINIT structure from 
shared memory, fill it in with the information specified in the API 
call, and send a WM_DDE_INITIATEACK message back to the re- 
questing window handle. A unique memory object is created each time 
the WinDdeRespond API is called. This process is illustrated in Fig- 
ure 2-4, 


Listing 2-2 shows the DdeConvWmDdelnitiateAck function. 
Called by the example client program, this function processes a 
WM_DDE_INITIATEACK message. 


Server PM Client 


WinDdeRespond (_) on WinSendMsg( ) (b) WM_DDE_INITIATEACK : 


Figure 2-4. Anatomy of the WinDdeRespond API As a positive response to a WM_DDE_IN- 
ITIATE message, a DDE server application issues a WinDdeRespond API (a). A shared memory 
object is allocated, large enough to contain a DDEINIT structure, and is initialized with the 
parameters specified in the API call. A WM_DDE_INITIATEACK message is sent to the window 
procedure associated with the specified window handle (b). A DDE client application processes 
the WM_DDE_INITIATEACK message and returns a value, which is returned as the result of 
the original WinDdeRespond API call (c). 


/* 


Kx 


at | 
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FURCT 1 On: DdeConvwmDdelnitiateAck 


Usage: Processes a “WM_DDE_INITIATEACK” message dispatched to a 
“WC _DdeConv” class window. 


Remarks: A “WM _DDE_INITIATEACK” message is sent when the WinDdeRespond 
API is issued. 


Guidelines: 


1) The value returned from processing this message is the value 
returned to the (server) application that issued the 
WinDdeRespond API. A return code of FALSE indicates that the 
receiving application cannot or does not want to engage in the 
conversation. 


2 ) The receiving application is expected to post a WM_DDE_TERMINATE 
message for all unwanted conversations regardless of the value 


returned Dy processing this message. 
MRESULT /* TRESUITS Error 1a) cacor me 
APIENTRY DdeConvWmDdelnitiateAck 
HWND hwnd /* handle of window receiving message * i} 
MPARAM mp 1 /* window handle of requesting application*/ 
MPARAM mp2 /* pointer to a DDEINIT structure * i 
BOOL fCaseSensitive = FALSE; 
BOOL fResult = FALSE; 
Obtain and set DDE transaction information... 
HWND hwndServer = HWNDFROMMP (mp1); 
PDDEINIT pDdeInit = (PDDEINIT) PVOIDFROMMP (mp2); 
POL pszAppName = pDdelnit->pszAppName; 
PSZ pszlopic = pDdelnit->pszlopic; 
PCONVCONTEXT pConvContext = DDEI_PCONVCONTEXT (pDdelInit); 
CHAR SszCpAppName [MAX_TEXTLENGTH]; 
CHAR SZCpTopic [LMAX_TEXTLENGTH]; 


Obtain “WC _DdeConv” window class info... 


PCONVINFO pConviInfo = (PCONVINFO) WinQueryWindowPtr 


Listing 2-2. Client: Process Initiate Acknowledgement 


/* 


K* 


/* 
xK* 
xK* 


my 


( hwnd 
) 9 


Obtain and set menu information... 


, QWL_USER 
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HWND hwndSubMenu = NULLHANDLE; 

MENUITEM mi; 

SHORT sItemCount = 0; 

SHORT sItemId = 0; 

Insert message and associated information into listbox. 


Note: Typically, an application receiving a DDE message will free the 
associated shared memory object after processing this message (as 


Shown at the end of this function. However, we save the original 
Shared memory object for subsequent retrieval by the user. The 
Shared memory object is freed when the listbox is destroyed or 
cleared. 
SHORT sSltemIndex = FrmiInsertListboxItem 
( hwndListBox 
, WM_DDE_INITIATEACK 
, UIMsgTime 
, (ULONG) pDdeInit 
ye 
If the state of this window is enabled, then it is already engaged in a DDE 


conversation. Once engaged, any subsequent acknowledgements are terminated. 


if (WinIsWindowEnabled (hwnd) ) 
{ 


fResult = WinDdePostMsg /* post a DDE message to... 
( hwndServer /* this requesting window handle, 
, hwnd {* from the “Conv” window handle, 
, WM_DDE_TERMINATE is an “Acknowledgement” message, 
» NULL im as defined in this memory object, 
, DDEPM_RETRY {* and retry if receiving queue is full. 


MS 


The receiver of a DDE message is responsible for the memory object 


associated with a DDE message. 


The receiver must either reuse or free 


the memory object. The example programs retain the original memory 


object for subsequent retrieval. 


The following statement would normally 


be executed at this point and is shown here for completeness. 


DosFreeMem (PVOIDFROMMP (mp2)); 


Listing 2-2. (continued) 
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return (MRFROMSHORT (FALSE)); 


If the ’state’ of the conversation link is ’none’ (its initial state), then 
then compare Application and Topic strings in the response to that of the 
conversation link. 


if (plonvinto-STsstate == CONVINFO_State_None) 


If a conversation context 1s associated with this conversation, 
determine context specific information. 


if (pDdelnit->offConvContext ) 


Determine if string comparisons are case sensitive. By default, 
all strings comparisons are not case sensitive. 


fCaseSensitive = pConvContext->fsContext & DDECTXT_CASESENSITIVE; 


If the current codepage is not equal to the conversation codepage, 
translate the AppName string from the conversation codepage to the 
current codepage. 


if (pConvContext->usCodepage != ConvContext.usCodepage) 
| 
fResult = WinCpTranslateString 
( hab 
, pConvContext->usCodepage 
, pDdelnit->pszAppName 
, ConvContext.usCodepage 
» MAX_TEXTLENGTH 
, SzCpAppName 
es 


If translation successful, adjust AppName pointer to translated 
ST PIUNG «0s 


if (fResult) 
pszAppName = szCpAppName; 


If the current codepage is not equal to the conversation codepage, 


translate the Topic string from the conversation codepage to the 
Current codepage. 


Listing 2-2. (continued) 


/* 
K* 
*xK* 


i 


/* 


K* 


=f 


/* 


K* 


ad 


/* 


K* 


a 


/* 
xK* 
K* 
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fResult = WinCpTranslateString 
( hab 
, pConvContext->usCodepage 
, pDdelnit->pszlopic 
, ConvContext.usCodepage 
» MAX_TEXTLENGTH 
, SZER1O81e 
iF 


If translation successful, adjust Topic pointer to translated 
SLPING «=> 


if (fResult) 
PSzlopie = BzCpl abies 


fResult = DdeCompareStrings 


( pConvinfo->szAppName 

, pszAppName 

, tCaseSensitive 

, ConvContext.idCountry 
, ConvContext.usCodepage 
ie 


If Application name strings matched, compare Topic strings... 


if (fResult) 


fFResult = DdeCompareStrings 


( pConvInfo->szTopic 

, pszlopic 

, fTCaseSensitive 

, ConvContext.idCountry 
, ConvContext.usCodepage 
); 


If Topic strings matched... 


if (fResult) 


Set the ’state’ of the conversation link to ’Alive’ and set the 
window handle of the responding application... 


Listing 2-2. (continued) 
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pConvinfo->fsState = CONVINFO_State_Alive; 
pConviInfo->hwndPartner = hwndServer; 


Notify our ‘owner’ of the acknowledgement so that it can add it to 
the ’Servers’ menu item... 


fResult = (BOOL) WinSendMsg 

WinQueryWindow (hwnd, QW_PARENT ) 
, UM_InitiateAck 

, MPFROMP (pConvInfo->szAppName) 

, MPFROMP (pConviInfo->szTopic) 

iE 


My 


Enable conversation link window... 


fResult = WinEnableWindow /* sets enabled state of... * | 
( hwnd /* this window to... * / 


, TRUE ha enabled. * f 
2 


The receiver of a DDE message is responsible for the memory object 
associated with a DDE message. The receiver must either reuse or free 
the memory object. The example programs retain the original memory 
object for subsequent retrieval. The following statement would normally 
be executed at this point and is shown here for completeness. 


DosFreeMem (PVOIDFROMMP (mp2)); 


return (MRFROMSHORT (TRUE)): 


Listing 2-2. (continued) 


In Listing 2-2, the client application first obtains a pointer to its 
conversation-information structure (allocated when the “WC_DdeConv” 
class window was created in DdeCreateConvWindow function). In- 
cluded in this structure are the application and topic name-strings 
specified in the original DDE Initiate request. These strings are com- 
pared to the corresponding strings of a WM-DDE-INITIATEACK mes- 
sage when matching requests to responses. Several checks are 
performed to ensure that the conversation link window is not currently 
engaged in a DDE conversation, which could happen if more than one 
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DDE server responded to the request. This is possible if more than one 
copy of a DDE server is executing, or different applications used the 
same application and topic name-strings. Also, the example programs 
retain messages (and their associated memory object) for subsequent 
examination. Typically, the application receiving a WM_DDE_INITI- 
ATEACK message will free this memory object immediately after proc- 
essing the message. The example programs free this memory object if 
the user has selected the clear menu option or when the application 
terminates. 
Several reasons exist why a server may elect not to respond: 


a The “application” string in the DDEINIT structure does not 
match the name of the server application. 

a The “topic” string does not match any of the currently sup- 
ported topics of the server. 

= It is busy, or it cannot handle another conversation. 


Note: There is no negative acknowledgement to the WM_DDE_INITI- 
ATE message. If the server does not or cannot acknowledge the request, 
it simply does not respond. 


The return value from the WinDdeRespond API is the same value 
returned by a client application when it processed the WM_DDE_INITI- 
ATEACK message. A non-zero value indicates success and a value of 
zero (or FALSE) indicates a failure. A failure can also occur in the API 
itself, for the following reasons: 


a The client window handle is no longer valid (for example, the 
client terminated for some reason). 

= Not enough shared memory was available to create a DDE- 
INIT structure. 

a The newly-created DDEINIT structure could not be given to 
the client application. (See “DosGiveSharedMem” for possi- 
ble reasons for failure. ) 

a The pszAppName and/or pszTopicName were NULL values. 
If either of these two items is not desired, then these fields 
should contain a pointer to a zero-length string. 


If the value returned is FALSE, an error occurred and the initiation 
processes. A conversation link is considered to have been established 
between two applications if and only if the DDE initiation process was 
successful. If any step fails, a conversation link is considered not to have 
been established. Typically, a server application will mark this conver- 
sation link as such and await the forthcoming WM_DDE_TERMINATE 
message. 
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It is possible that a WM_DDE_TERMINATE message never arrives 


(due to some other internal error, or the death of the originating client 
application). In this case, the corresponding conversation window will 
not be destroyed until the server application terminates, or by some 
other technique used by the server application to destroy the window 
(possibly on some timeout factor). 


Listing 2-3, showing the WmDdelnitiate function, is called by the 


example server program to process a WM_DDE_INITIATE message. 
The remarks in the Guidelines portion of the function prologue, along 
with the commentary statements, describe this process. A summary of 
these requirements is listed in the “Guidelines” section at the end of this 
chapter. 


Function: 


Usage: 


Remarks: 


Guidelines: 


1) 


2) 


ee, 


WmDdelInitiate 


Processes a “WM _DDE_INITIATE” message dispatched to a 
“WC Client” class window. 


A WM_DDE_INITIATE message is sent via the WinDdelnitiate API 
issued by a client application. 


If the status of the server is currently busy, the do not 
respond to this request. 


Determine if the request included a Conversation Context 
SLPUCEUre. 


a) If this structure is present, determine if string 
comparisons are case sensitive. String comparisons are case 
insensitive by default. 


b) If this structure is present, determine if the codepage 
jdentified in this structure is different than the servers 
codepage. If it is, translate these strings and compare 
them to the corresponding string or strings supported by this 
server. 


If the AppName is a zero-length string, then any DDE server may 
respond. If the AppName is not a zero-length string, then 
compare the string in the request to the string identifying this 
server according to the conversation context parameters 
described above. 


Listing 2-3. Server: Process Initiate Request 
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Kx 

ae 4) If the Topic is zero-length string, respond once for each topic 

oe currently supported by this server. It iS possible that a topic 

we is Supported at various times. A server application is not 

we required to respond to previous requests for a topic that was 

ay not previously available. 

K* 

ne =>} For each response, create a separate and unique window to handle 

ae the DDE conversation. This ensures that a window handle pair 

am will uniquely identify the conversation. 

kK* 

ores 6 ) Free the DDEINIT structure. NOTE: The example programs found in 

sie this book retain all DDE messages for later replay, however, the 

i location at which this structure is freed is specified in the 

sit code but is commented out. 

*K* 

xx This message is always sent. 

* ka SS eS SS SS SS SS = = *K / 
MRESULT s* FResuit: ECO TAdicator dj 
APTENTRY WmDdeInitiate 

( 

HWND hwnd /* handle of window receiving message ot 

MPARAM mp1 /* window handle of requesting application*/ 
, MPARAM mp2 /* pointer toa DBDEINIT structure a i 
) 

ULONG enSstring = OL; 

BOOL fResult = FALSE; 

BOOL fCaseSensitive = FALSE; 

BOOL fStringsMatch = TRUE; 

HENUM henum = (HENUM) 0; 

HWND hwndConv = (HWND) 0; 

HWND hwndPartner = HWNDFROMMP (mpl); 

HWND hwndTopic = (HWND) 0; 

ie : 

a* Obtain and sét DDE transaction 1nTormation.. . 

* i 
PDDEINIT pDdeInit = (PDDEINIT) PVOIDFROMMP (mp2); 


PCONVCONTEXT pInitContext = DDEI_PCONVCONTEXT (pDdelInit); 
PCONVCONTEXT pConvContext = NULL; 


PSZ 
Pad 
USHORT 
USHORT 
ULONG 
ULONG 
CHAR 
CHAR 


pszAppName = pDdelInit->pszAppName; 

pszlIopic = pDdelnit->pszlopic; 

usAppName = strien (pDdelInit->pszAppName) ; 
usTOpic = strlen (pDdelnit->pszTopic); 
ulCountry = ConvContext.idCountry; 
ulCodePage = ConvContext.usCodepage; 


szCpAppName [MAX_TEXTLENGTH]; 
szCpTopic  [MAX_TEXTLENGTH]; 


Listing 2-3. (continued) 


/* 


kK* 


a 


/* 
xK* 
x* 


ef 


/* 


Kx 


al 


/* 


kK* 


at | 


/* 
kK* 
K* 
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CHAR Sz Op1C [LMAX_TEXTLENGTH]; 
Insert message and associated information into listbox. 


Note: Typically, an application receiving a DDE message will free the 
associated shared memory object after processing this message (as 
Shown at the end of this function. However, we save the original 
Shared memory object for subsequent retrieval by the user. The 
Shared memory object is freed when the listbox is destroyed or 
cleared. 


SHORT sltemIndex = FrminsertListboxItem 
( hwndListBox 
, WM DDE_INITIATE 
, UlIMsgTime 
, (ULONG) pDdelnit 
i 
Check the enabled state of the main window... 
fResult 


= WinlsWindowEnabled 
( hwnd 
ys 


if the main window is not enabled, the server is not yet ready to accept 
initiate requests... 


if (fResult == FALSE) 
{ 

return (MRFROMSHORT (0)); 
} 


Check if the server is busy... 


fResult = WinIsMenultemChecked 
( hwndMenuStatus 

, IDM_STATUS_BUSY 

- 


If it is, a server application is not required to respond... 
if (fResult) 
return (MRFROMSHORT (0)); 


If a Conversation Context structure is present, determine if Topic name 
and Item name strings are to be compared case-sensitive... 


Listing 2-3. (continued) 


a 


/* 


K* 


a 


/* 
kK* 
K* 


ae 


/* 
*xx* 
*xK* 


a 


/* 


*x If this server is not an instance of the requested application, 
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if (pDdelnit->offConvContext) 


fCaseSensitive = pInitContext->fsContext & DDECTXT_CASESENSITIVE; 


If an application name was specified, compare the requested application 
name-string against our server name-string... 


if (usAppName ) 


Check if code page translation is required... 


if (pDdeInit->offConvContext 
&& plnitContext->usCodepage != ConvContext.usCodepage) 
fResult = WinCpTranslateString 
( hab 
, pInitContext->usCodepage 
, pszAppName 
, ConvContext.usCodepage 
, MAX_TEXTLENGTH 
, SzCpAppName 
Ps 


If successful translation, adjust Application name-string pointer to 


address translated string... 


if (fResult 
{ : 
pszAppName = szCpAppName; 


Compare the requested Application name-string to our server 
name-string... 


fStringsMatch = DdeCompareStrings 

( (PSZ) szAppName 

, pszAppName 

, fTCaseSensitive 

, ConvContext.idCountry 
ConvContext.usCodepage 


Listing 2-3. (continued) 


then return 


25 


{/* 


k* 
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FALSE indicating a non-fatal error occurred. 


if 


(fStringsMatch == FALSE) 


Typically, the memory object associated with the message would be freed 


here. However, the example program retains this information in a listbox 


for subsequent examination by the user. The following code statement 
1s shown here to illustrate how a typical application might function... 


DosFreeMem (pDdelInit); 


return ((MRESULT) FALSE); 


a topic was specified... 


(usTopic) 


If a conversation context structure was included in the request and the 
Specified codepage is different than the codepage of the this server 
application, then translate the string to the servers codepage. 


if (pDdeInit->offConvContext 
&& plnitContext->usCodepage != ConvContext.usCodepage) 
fResult = WinCpTranslateString 
( hab 
, pInitContext->usCodepage 
, DSZILORIE 
, ConvContext.usCodepage 
» MAX_TEXTLENGTH 
, SZCPTOpIE 
)¥- 


If successful translation, adjust topic name-string pointer to 
address translated string... 


if (fResult) 
pszlopic = szCplopic; 
else 


Typically, the memory object associated with the message would be 


Listing 2-3. (continued) 
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freed here. However, the example program retains this information 
in a listbox for subsequent examination by the user. The following 
code statement is shown here to illustrate how a typical 
application might function... 


DosFreeMem (pDdelInit); 


return COMRESULT) FALSE): 


At this point it has been determined that the initiate request is for this 
server application and all translations (if any) have occurred. Next, the 
scope of the response must be determined. That is, if a topic was specified, 
does this server support that topic? If the topic was a zero-length string, 
then this server must respond once for each supported topic. In this 

example server application, topics are Supported by the existence of a 
WC_DdeTopic class window. This class of window is ALWAYS a child of the 
applications main window. Therefore, a list of supported topics can be 
obtained by enumerating the applications main window as shown here... 


henum = WinBeginEnumWindows (hwnd); 
for each window found... 


while (hwndTopic = WinGetNextWindow (henum) ) 


The Topic name-string associated with a WC_DdeTopic class window can be 
obtained by querying the window text of the window... 


cbString = WinQueryWindowlext 
( hwndTopic 
, sizeof (szTopic) 


, SZTORIE 
Ms 
Check the length of the returned string... 
if (cbString == 0) /* this should never fail! If it does, bo | 
continue; /* continue to the next child window... sa | 


If usTopic is greater than zero (0), then the originator of the DDE 
initialization request specified a specific topic name. In this case 
we have to check for a match on topic name-strings. Note: the topic 
name will have already been translated above. 


Listing 2-3. (continued) 
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* 
if <uslopic) 
{ 
fStringsMatch = DdeCompareStrings 
( szTopic 
» pSzlopic 
, fCaseSensitive 
, ConvContext.idCountry 
, ConvContext.usCodepage 
ie 
/* 
wie ET SUrings cid fot match... 
* 
if (fStringsMatch == FALSE) 
{ 
continue; /* continue to next child window... =y 
} 
/* 
ies At this point it has been determined that a response is required. So copy 
ba the contents of the Conversation Context structure. We do this so that 
“2 if we FREE the original DDEINIT memory object at the end of this function 
we and still retain the conversation information. If no conversation 
bahia context structure was included, then set this variable to NULL... 
ia 3 
pConvContext = (pDdelnit->offConvContext) 
? DdeCopyConvContext (pInitContext) 
: NULL; 
/* 
bala Create a new window to handle the conversation link... 
a? | 
hwndConv = DdeCreateConvWindow 
( hwndTopic /* parent (topic) window handle ~y 
hwndPartner /* requesting DDE client window handle ae 
(PSZ) szAppName /* application name my 
, {PSZ) SzTopic /* topic name = 
, pConvContext /* pointer to CONVCONTEXT structure *y 
PS 
/* 


*k Tf a conversation window was successfully created, respond to the 
*k requesting clients initiation request. Otherwise, display an error 
**k message to the user indicating an application error. 


ad | 
if ChwndConv) 
USHORT fsState; 
/* 
we The WinDdeRespond API creates a new DDEINIT structure and sends a 


Listing 2-3. (continued) 


*K* 
*K* 
kK* 
kK* 
K* 


a 


K* 
K* 
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WM_DDE_INITIATEACK message back to the requesting application. A 
pointer to this newly created DDEINIT structure is passed in message 
parameter two (mp2) of the WM_DDE_INITIATEACK message. The value 
returned by the WinDdeRespond API is the value returned by the client 
application when it processed the WM_DDE_INITIATEACK message. 


fResult = (BOOL) WinDdeRespond 
( hwndPartner 
, NwndConv 
, (PSZ) szAppName 
, {P3242 szlepic 
, (PCONVCONTEXT) &ConvContext 
ye 


Depending on the return value, the Conversation window is set to 
an ’Active’ state if the return value was TRUE, or to an ’Zombie’ 
State if the WinDdeRespond failed or the client application 
indicated that an error occurred. In either case, we set the 
conversation window to a non-functional state. 


if (fResult) 


Keep a count of how many conversation links this server is 
Currently engaged in... 


cLinks}®*: 


Enable the “Terminate All” menu-item for subsequent termination 
of conversation links... 


fResult = WinEnableMenultem 

( hwndMenu 

, IDM_LINKS_TERMINATE_ALL 
, TRUE 
if 


Here we sub-class the conversation window with a new window 
procedure. This window procedure allows for Server specific 
behavior of a conversation link. 


pfnDdeConvWindowProc = WinSubclassWindow 
( hwndConv 
DdeServerConvWindowProc 
iG 


Set the state of the conversation to “Alive”. In this state, a 
conversation responds to all client requests. 


Listing 2-3. (continued) 
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iad 


K* 


¥} 


/* 


K* 


mf 
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fsState = CONVINFO State Alive; 
} 
else 
{ 


In this case, either the client application responded with a zero 
(0) or the WinDdeRespond API failed. Here we set the state of 
the conversation to that of a “Zombie” (neither dead or alive). 
In this state, a conversation window does not respond to any 
client requests except a WM_DDE_TERMINATE. If should be noted 
that in the case of the API failing, no WM_DDE_TERMINATE message 
is forthcoming and the conversation link window will exist until 
the server application terminates... 


fsState = CONVINFO_State_Zombie; 
} 


Notify Conversation window of its new State... 


fResult = (BOOL) WinSendMsg 
( hwndConv 
, UM_SetState 
, MPFROM2ZSHORT (fsState, SS REPLACE) 
, MPVOID 


} 
Free system resources used for enumeration... 
fResult 


WinEndEnumWindows 
h 


( henum 
hs 


A Server application is responsible for freeing the DDEINIT memory object. 
These example programs retain this information for subsequent replay. A 
pointer to this memory object is stored in its corresponding listbox entry 
and is freed when the listbox entry is deleted. The following API is 
listed here for completeness of the example code and should be uncommented 
if used by an application that does not need to preserve this data. 


DosFreeMem (pDdelnit); 


return MRFROMSHORT (TRUE); 


Listing 2-3. (continued) 
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NATIONAL LANGUAGE SUPPORT (NLS) 


Much of the DDE protocol involves working with and comparing ASCII 
text strings; for example, topic and item names. Applications that im- 
plement NLS use codepages to support the character set of their par- 
ticular language (see Chapter 16, “National Language Support,” in 
Volume 1 of the OS/2 Programming Guide for more information regard- 
ing capabilities and considerations of NLS support). Different code- 
pages impose additional requirements when interpreting text strings. 
Obviously, if one application is using a different codepage than another, 
string comparisons could fail without knowing which codepage the 
string is based on. 

The DDE protocol requires an application to do string comparisons on 
the following items: 


a Application Name 
x Topic Name 
= Item Name 
» Commands (also called protocols; see “Execute” in Chapter 4) 


To facilitate the need to convey this information between applications 
using different languages, the CONVCONTEXT (conversation context) 
structure, illustrated in Figure 2-5, is supported. This structure defines 
the Context of an application, including its codepage, country, and lan- 
guage information. (For detailed information regarding this structure, 
see “CONVCONTEXT” in Appendix A.) 

If an application is NLS-sensitive, it must include this structure dur- 
ing the DDE initiation process. Inclusion of this structure is optional. 
When not required, the initiating or responding application can set 
the pContext parameter of the WinDdelnitiate or WinDdeRespond 
API to NULL. Typically, the receiver of a WM_DDE_INITIATE or 


¢ idCountry 


fsContext usCodepage usSublangID 
Figure 2-5. CONVCONTEXT Structure 
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Guidelines 
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WM_DDE_INITIATEACK message will save this information and refer 
to it if and when string comparisons are required. 

In addition to codepage and country information, the conversation 
context structure also specifies how string comparisons are made. 
String comparisons are either case-sensitive or case-insensitive. By de- 
fault, string comparisons in the DDE protocol are case-insensitive. By 
setting the DDECTXT_CASESENSITIVE flag in the fsContext field of 
this structure, all string comparisons in the context of the conversation 
are case-sensitive. The helper function DdeCompareStrings simpli- 
fies this process and is listed in Appendix F. 


General 


# A conversation link is considered to be established between 
a client and a server application if and only if the server 
application returns from the WinDdeRespond API success- 
fully; that is, the client application returned a non-zero 
(TRUE) value in response to the WM_DDE_INITIATEACK 
message. 


A client application must: 


a Free the shared memory object containing the DDEINIT 
structure. 

a Terminate all unwanted conversation links. For each un- 
wanted conversation link, it must post a WM_DDE_TERMI- 
NATE message. 

# Include a CONVCONTEXT structure if it is NLS-sensitive. 


A server application must: 


# Free the shared memory object containing the DDEINIT 
structure. 

# Respond if the Application name matches that of the server, 
or if the Application name is a zero-length string. A server 
does not have to respond if it is busy. 

# Use the information contained in a CONVCONTEXT struc- 
ture to compare strings if one is present. Include a CON- 
VCONTEXT structure in its response if the requesting 
applications context is different from that of the server. 
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Note: It is always legal to include a CONVCONTEXT struc- 
ture in a response, even if the context is the same. 

Check the return code from the WinDdeRespond API. If 
this API is successful, a conversation link is considered to 
be established between the originating client and the re- 
sponding server applications. If this API fails, no conver- 
sation link is established. However, it is possible that a 
WM_DDE_TERMINATE message was posted by the client 
application. 


Ensure that each acknowledgement contains a unique win- 
dow handle. 


The DDE Data Item 


A DDE data item is a object that is be passed in a DDE transaction. A 
data item might be a single integer, a string, several paragraphs of text 
or a bitmap. 


ANATOMY OF A DDE DATA ITEM 


A data item is contained in a memory object that must be allocated 
from shared memory using the DosAllocSharedMem API. It must be 
allocated from shared memory to facilitate the process of giving the 
receiving application access to the memory area. The memory object 
must be large enough to hold a DDESTRUCT structure (as illustrated 
in Figure 3-1), the item name-string, and any data representing the 
item. (For a detailed description of each element, see “DDESTRUCT” 
in Appendix A.) 


fsStatus offszItemName ItemName 


Reese a ee | 


cbData usFormat offabData Data 


Figure 3-1. Anatomy of a DDESTRUCT Structure 
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Structure Definition 


typedef struct _DDESTRUCT 


ULONG 
USHORT 
USHORT 
USHORT 
USHORT 

} DDESTRUCT; 


cbData; /* size of data portion (in bytes). ial J 
fsStatus; /* transaction status flags * 
usFormat; /* registered DDE format identifier wf 
offszItemName; /* offset (in bytes) to start of item name-string all 
offabData; /* offset (in bytes) to start of data portion a | 


typedef DDESTRUCT *PDDESTRUCT; 


DDE DATA FORMATS 


Format Identifier 


Each data item exchanged must specify the format of the data being 
exchanged. A format identifier must be unique and set in the usFormat 
field of aDDESTRUCT structure in a DDE transaction. An application 
can use any of the clipboard format identifiers listed in Table 3-1 and 
declared in the PMWIN.H header file. In addition, an application can 
use the system-defined standard format DDEFMT_TEXT for exchang- 
ing text data. 

An application can define private data formats by registering the 
private format name-string with the system atom table. The system 
atom table guarantees that registered name-strings are identified by a 
unique number. 

An application can also register any of the standard format name- 
strings listed in Table 3-2. (For a complete and updated listing of 
format name-strings, refer to the PMWIN.H header file provided in 
the OS/2 tool-kit.) The value returned from registering a standard 
DDE format name-string is guaranteed not to conflict with standard 
clipboard formats and an application can use either value interchange- 
ably. 


TABLE 3-1. Clipboard Format Identifiers 


#define CF_TEXT 

#define CF_BITMAP 
#define CF_DSPTEXT 
#define CF_DSPBITMAP 
#define CF_METAFILE 
#define CF_DSPMETAFILE 
#define CF_PALETTE 
#define CF_ MMPMFIRST 
#define CF MMPMLAST 


OOoOIonIrwNdr 


A 


Data Format Layout 
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TABLE 3-2. DDE Format Name-:strings 


#define SZFMT_TEXT “HI” 

#define SZFMT_BITMAP “#2” 

#define SZFMT_DSPTEXT “#3” 

#define SZFMT_DSPBITMAP “#4” 

#define SZFMT_METAFILE “HB” 

#define SZFMT_DSPMETAFILE “#6” 

#define SZFMT_PALETTE “H#Q” 

#define SZFMT_SYLK “SYLK” 

#define SZFMT_DIF “Dit” 

#define SZFMT_TIFF oo bv 

#define SZFMT_OEMTEXT “OemText” 
#define SZFMT_DIB “Dib” 

#define SZFMT_LINK “Link” 

#define SZFMT_METAFILEPICT “MetaFilePict” 
#define SZFMT_DSPMETAFILEPICT “DspMetaFilePict” 
#define SZFMT_CPTEXT “Codepage Text” 


The following code fragment illustrates an example of how an appli- 
cation would register the “DDEFMT_Name’” private data format. 


HATOMTBL hatomtb| 
USHORT usformatld 


WinQuerySystemAtomTable 
WinAddAtom (hatomtbl, “DDEFMT_Name”); 


While appearing similar, DDE formats are not the same as clipboard 
formats. Clipboard formats identify handle types, whereas DDE for- 
mats identify the layout of the data contained in the data portion of 
a DDESTRUCT structure. For example, if the format identifier speci- 
fied a bitmap (CF_BITMAP), the data portion would contain a valid 
BITMAPINFOZ2 structure. 

The remainder of this section lists standard data format layouts. 
Included in the list are the defined value of each data format (as defined 
in the PMWIN.H header file). These values are shown within brackets 
[ ]. For example, given the following definition: 


DDEFMT_TEXT [0x0001] 


DDEFMT_TEXT is the format identifier and [0x0001] is its correspond- 
ing defined value. 
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Text 


Display Text 


NULL (0x00) terminated the ANSI character-set character string. The 
string can include a carriage return (Ox0D) and/or a line-feed (0x0A) 
character to mark the end of a line. 

The following are valid format identifiers that can be used inter- 
changeably to identify the TEXT format: 


# Registered atom identifier of the SZFMT_TEXT [#1] format 
name-string 

e DDEFMT_ TEXT [0x0001] 

a CF_ TEXT [1] 


The layout of this format is identical to that of the TEXT format. This 
format is textual representation of a private data format. The following 


are valid format identifiers that can be used interchangeably to identify 
the DISPLAY TEXT format: 


= Registered atom identifier of the SZFMT_DSPTEXT [#3] 
format name-string 
ae CF DSPTEXT [8] 


Bitmap Information and Data 


Display Bitmap 


Depending on the version of the OS/2 Operating System, this format 
consists of either a BITMAPINEFO (version 1.2 and 1.3) or a BITMAP- 
INFO2 (version 2.0 and above) structure. The following are valid for- 
mat identifiers that can be used interchangeably to identify the 
BITMAP format: 


= Registered atom identifier of the SZFMT_BITMAP [#2] for- 
mat name-string 
a CF_BITMAP [2] 


Note: In the OS/2 operating system, no distinction is made between 
device-dependent and device-independent bitmaps, as in the Windows 
environment. Although the SZFMT_DIB format name-string is defined 
in the PMWIN.H header file, its format is identical to that of a bitmap. 


The layout of this format is identical to that of the BITMAP format. This 
format is the bitmap representation of a private data format. The 


Metafile Bits 


Display Metafile 


Metafile Picture 
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following are valid format identifiers that can be used interchangeably 
to identify the DISPLAY BITMAP format: 


= Registered atom identifier of the SZFMT DSPBITMAP [#4] 
format name-string 
» CF DSPBITMAP [4] 


Typically these are the bits retrieved via the GpiQueryMetafileBits 
API. The following are valid format identifiers that can be used inter- 
changeably to identify the METAFILE format: 


= Registered atom identifier of the SZFMT METAFILE [#5] 
format name-string 
a CF METAFILE [5] 


The layout of this format is identical to that of the METAFILE format. 
This format is the metafile representation of a private data format. The 
following are valid format identifiers that can be used interchangeably 
to identify the DISPLAY METAFILE format: 


# Registered atom identifier of the SZFMT_DSPMETAFILE 
[#6] format name-string 
a CF_DSPMETAFILE [6] 


The layout of this format consists of an MFP structure. Typically the 
metafile bits are retrieved by issuing the GpiQueryMetafileBits API; 
to this extent, this format is identical to the METAFILE format. This 
format differs from the METAFILE format in that it includes additional 
information defining the metafile bits. The following is a valid format 
identifier that can be used to identify the METAFILE PICTURE format: 


= Registered atom identifier of the SZFMT_METAFILEPICT 
[“MetafFilePict”] format name-string 


For more detail description of the MFP structure, see Appendix A. 
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Display Metafile Picture 


The layout of this format is identical to that of the METAFILE PICTURE 
format. This format is the metafile picture representation of a private 
data format. The following is a valid format identifier that can be used to 
identify the DISPLAY METAFILE PICTURE format: 


=» Registered atom identifier of the SZFMT_DSPMETA- 
FILEPICT [“DspMetaFilePict”] format name-string 


Palette Information and Data 


Codepage Text 


Link 


This format consists of a PALETTEINFO structure. The following are 
valid format identifiers that can be used interchangeably to identify the 
PALETTE format: 


= Registered atom identifier of the SZFMT_PALETTE [#9] 
format name-string 
a CF PALETTE [9] 


This format allows applications to exchange text in a specific codepage 
without having to establish a CONVCONTEXT sensitive conversation. 
This format consists of a CPTEXT structure. The textual portion of this 
structure must be in TEXT format. The following is a valid format 
identifier that can be used to identify the CODEPAGE format: 


= Registered atom identifier of the SZFMT_CPTEXT [“Code- 
page Text”] format name-string 


For a more detailed description of the CPTEXT structure, see Appen- 
dix A. 


This format contains initiation information required to establish a DDE 
conversation link with the associated data item. It is typically used in a 
paste-link operation, commonly found in Windows applications. A paste- 
link operation uses the clipboard as a shortcut to obtaining information 
required to establish a link with a DDE server application. 

If an application copies data to the clipboard and it is capable of 
rendering that data item dynamically, it typically includes the link 
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format when placing data on the clipboard. Another application can 
then extract this information, establish a DDE conversation, and re- 
quest the specified data item without having to perform the DDE 
initiation process. The layout of a the link format is as follows: 


AppName(0x00)TopicName(0x00)ItemName (0x00)(0x00) 


The following is a valid format identifier that can be used to identify 
the LINK format: 


= Registered atom identifier of the SZFMT_LINK [“Link”] for- 
mat name-string 


Symbolic Link (SYLK) 


Symbolic Link format (developed and supported by Microsoft® Corp.) is 
used to exchange spreadsheets in an ASCII text format. A carriage 
return (0x0D) and a line-feed (0x0A) character mark the end of a line. 

The following is a valid format identifier that can be used inter- 
changeably to identify the SYLK format: 


# Registered atom identifier of the SZFMT_SYLK [“Sylk”] for- 
mat name-string 


Data Interchange Format (DIF) 


Data Interchange Format (developed by Software Arts) is used to trans- 
fer data to a Visicalc spreadsheet program. The following is a valid 
format identifier that can be used to identify the DIF format: 


= Registered atom identifier of the SZFMT_DIF [“Dif”] format 
name-string 


For further information regarding the details of this format, see the 
documentation provided by the product. 


Tag Image File Format (TIFF) 


Tag Image File Format (developed by Microsoft, Aldus, and Hewlett- 
Packard) describes bitmapped data. The following is a valid format 
identifier that can be used to identify the TIFF format: 


# Registered atom identifier of the SZFMT_TIFF [“Tiff’] for- 
mat name-string 
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For further information regarding the details of this format, see the 
documentation provided by the product. 


Original Equipment Manufacture (OEM) Text 


Original Equipment Manufacture Text is a format that was a carryover 
from the Windows conversion. In a Windows environment, it specified 
that the text was defined in the IBM extended character-set. The OS/2 
operating system does not use character-sets in the same manner as did 
Windows; rather, it uses codepages. 

This format indicates that the associated text has been created using 
codepage 437 (U.S.-ENGLISH ASCII codepage). The layout of this 
format is identical to that of SZFMT TEXT: 


= Registered atom identifier of the SZFMT_OEMTEXT 
[“OemText”] format name-string 


DDE Transactions 


A DDE transaction is the exchange of DDE messages between a client 
and a server application. All DDE transactions are one-way; that is, a 
client application always initiates the transaction and a server always 
responds to the transaction. The only exception to this rule is the 
terminate transaction, which can be initiated by either the client or the 
server application. 

DDE transactions are divided into the following six categories: 


= Request—request a one-time data transfer (cold-link) 
Advise—request a permanent data-link be established 
(warm-link or hot-link) 

Unadvise—request to terminate a data-link 

Poke—request that a data item be updated 
Execute—request that a command or commands be executed 
Terminate—request to terminate a conversation link 


DDE transaction messages consists of the following items: 
= A message identifier indicating the type of transaction 


= The window handle of the application that originated the 
message 
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Prototype 


MRESULT WinDdePostMsg 


Example Code 


APIRET 
APTENTRY 
| 

BOOL 


/* 


*x Allocate a piece of shared memory and initialize it with the following parameters. 


a 
pDdeStruct 


fResult 


ExampleFunction () 


# A pointer to a shared memory object consisting of a DDE- 
STRUCT structure containing information specific to the 
transaction (with the exception of the WM_DDE_TERMI- 
NATE message, in which case no pointer is given) 


DDE transactions are issued by calling the WinDdePostMsg API. As 
implied by its name, this function posts a DDE message. In addition, it 
gives the memory object to the process associated with the destination 
window handle, which frees the originator from the burden of determin- 
ing the destination process identifier issuing the DosGiveSharedMem 
API itself. The following code fragment illustrates issuance of a DDE 
transaction. (For a complete description see “WinDdePostMsg” in Ap- 
pendix C.) 


( HWND 
, HWND 
, USHORT 


, PDDESTRUCT 


, ULONG 
E 


fResult; 


PDDESTRUCT pDdeStruct; 


( 


“™ ll ~~ 
we 


DdeMakeDDEStruct 


“TtemName” 


WinDdePostMsg 
hwndServer 


, hwndClient 
, WM_DDE_REQUEST 


pDdeStruct 
DDEPM_RETRY 


hwndTo /* destination window handle 
hwndFrom /* originating window handle 
usMsgld /* DDE message identifier 


pDdeStruct /* pointer to shared memory object 


ulOptions /* post options 


/* 
/* 
/* 
/* 
/* 


/* 
/* 
/* 
/* 
i= 


DDE item name-string 

address of data-buffer 

size of data (in bytes) 
registered DDE format identifier 
DDE status flags 


destination window handle 
originating window handle 

request data item 

address of a DDESTRUCT structure 
retry if destination queue is full 


a 
oy 
ay 
at 
a 


=} 
oi i 
| 
al 
at | 


oy 
oF 
at 4 
of | 
mf 


PDDESTRUCT 
APIENTRY 


PSZ 
PVOID 
ULONG 
USHORT 
USHORT 


APIRET 
USHORT 
PDDESTRUCT 
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The originator of the DDE transaction must allocate a memory object 
from shared memory using the DosAllocSharedMem API. The mem- 
ory object must be allocated as giveable and large enough to hold a 
DDESTRUCT structure (as was illustrated in Figure 3-1), the item 
name-string, and any data representing the item. (See “DDESTRUCT” 
in Appendix A for further information regarding this structure.) 

Caution: In order to successfully give the memory object, the address 
of the memory object must be a base address as returned by the 
DosAllocSharedMem API. It cannot be an offset such as that re- 
turned by the DosSubAllocMem API. 

The following code fragment, extracted from the DdeMakeDDE- 
Struct function, illustrates allocation of a shared memory object. This 
function encapsulates and simplifies the task of creating a DDE- 
STRUCT structure suitable for a DDE transaction. (See Appendix F-.) 


/* pointer to DDESTRUCT structure a | 
DdeMakeDdeStruct 
pszItemName /* pointer to item name-string ial 
pvData /* pointer to rendered data (if any) al 
cbData /* size of rendered data (if any) * 
usFormat /* registered DDE format identifier ia 
fsStatus i* DOE Status Tlaqs */ 
ApiRet; 
cbItemName; 
pDdeStruct; 


[other function statements... ] 


ApiRet= DosAllocSharedMem 


(PPVOID) &pDdeStruct /* base address of shared memory object =f 
» APSZ NULL /* unnamed memory object =f 
, sizeof (DDESTRUCT ) /* size of memory object (in bytes), mf 
+ cbItemName /* size of item name-string, a | 
+ cbData /* size of data (if any), x f 
, PAG_COMMIT /* all pages are initially committed a | 
| OBJ_GIVEABLE /* memory object is giveable mf 
| PAG_READ /* read access allowed a 
| PAG_WRITE /* write access allowed oP 


[remainder of function... ] 


To better understand DDE transactions, it is helpful to first under- 
stand DDE Responses and Message Synchronization. These discussions 
will lay the framework around which DDE transactions are processed 
and will make discussions of them more clear. 
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DDE RESPONSES 


For every DDE transaction issued, a response is expected, either posi- 
tive or negative. The DDE protocol defines three response messages: (1) 
the WM_DDE_ACK message; (2) the WM_DDE_DATA message; and (3) 
the WM_DDE_TERMINATE message. 


Positive Acknowledgement 


BOOL 
PDDESTRUCT 
PSZ 

HWND 


A positive acknowledgement is issued by setting the DDE_FACK flag in 
the fsStatus field of a DDESTRUCT structure and posting a 
WM_DDE_ACK message. An application issuing this response can either 
create a new shared memory for the DDESTRUCT structure or reuse 
the DDESTRUCT structure of the original request it is acknowledging. 

Reusing the original memory object is a common technique for ac- 
knowledging an Execute request. Since the acknowledgement for an 
Execute request must contain the original command strings, it is sim- 
pler to just reuse this memory object rather than creating a new one and 
copying the data. The following code fragments show the two methods 
of acknowledgement. Both examples assume that a valid pointer to a 
DDESTRUCT structure was passed in message parameter two (mp2) 
of the DDE message, as follows: 


fResult; 

pDdeStruct (PDDESTRUCT) PVOIDFROMMP (mp2); 
pszItemName = (PSZ) DDES_PSZITEMNAME (pDdeStruct); 
hwndRequester = HWNDFROMMP (mp1); 


A. Creating a new shared memory object: 


pDdeStruct = DdeMakeDdeStruct 

( pszItemName /* Item name-string = 
» NULL /* pointer to data (Not applicable) */ 
, OL /* size of data (in bytes) iol | 
, pDdeStruct-usFormat /* DDE format of original request ak 
, DDE_FACK /* positive acknowledgement a 


Ds 

if (pDdeStruct) 

fResult = WinDdePostMsg 
( hwndClient 

, hwnd 

WM DDE_ACK 

pDdeStruct 
DDEPM_RETRY 
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B. Reusing the original memory object: 


DDGESLPUucL*-TSSstatus — ODE_FACK: 
fResult = WinDdePostMsg 

( hwndClient 

, hwnd 

, WM_DDE_ACK 

, pDdeStruct 

, DDEPM_RETRY 

ie 


Note: The DDE protocol states that the receiver of a DDE message 
is responsible for the memory object associated with the message. If 
an application chooses method A, it must free the memory object by 
issuing a DosFreeMem API on the memory object. If an application 
chooses method B, the memory object is freed by the WinDdePostMsg 
API (unless the DDEPM_NOFREE option was specified). In either 
case, the receiving application has the final responsibility for the mem- 
ory object. 


Negative Acknowledgement 


Data 


A negative acknowledgement is identified by the absence of the 
DDE_FACK flag in the fsStatus field of the DDESTRUCT structure 
when a WM_DDE_ACK message is posted. Reuse of the memory object 
associated with the original request is valid as mentioned in the positive 
acknowledgement. The above examples are also applicable to the nega- 
tive acknowledgement, with the following exception: DDE_NOTPRO- 
CESSED and/or DDE_FBUSY status flags are specified rather than 
DDE_FACK. 

Note: The DDE_NOTPROCESSED flag should not, in itself, be con- 
sidered the negative acknowledgement indicator. Although this flag (like 
the DDE_FBUSY flag) is only valid in the context of a negative acknow- 
ledgment, its intended use is to indicate that the responding application 
does not support the request. (See Appendix E, “DDE Status Flags,” for 
more information regarding these flags.) 


A (WM_DDE_DATA) data message is posted as a positive response to a 
Request transaction. Also, WM_DDE_DATA messages are posted as 
delayed responses to a previous Advise request. Both the Request and 
the Advise transactions are discussed later in this section. 
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Terminate 


Guidelines 
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The (WM_DDE_TERMINATE) terminate message performs a dual pur- 
pose in the DDE protocol: It is used as both a request and a response 
message. This message is only valid as a response to a Terminate 
request. (See “Terminate Request” later in this section for additional 
information regarding the WM_DDE_TERMINATE message.) 

Table 4-1 lists each DDE transaction and which of these three mes- 
sages are expected in response. 


Caution: 


An application should not attempt to modify a memory ob- 
ject once it has been posted. Modification of the object would 
compromise the integrity of the transaction. Furthermore, if 
the DDEPM_NOFREE option was not specified in the 
WinDdePostMsg call, a system exception would occur if the 
memory object was referenced. 

Once a conversation link has been established, DDE mes- 
sages can originate from any window, even one that did not 
initially establish the conversation link. Because the window 
handle can be different on each request, a DDE application 
should always respond to the window handle specified in 
message parameter one (mp1) of a DDE message. 


Previous documentation indicated that the data portion of a 


DDESTRUCT structure could contain embedded pointers and/or han- 
dles. Although not prohibited, embedded pointers and handles should 
never be passed in this area! Their usage is discouraged to ensure 


TABLE 4-1. DDE Transaction Responses 


Transaction Positive Negative 
Request WM_DDE DATA WM_DDE_ ACK (1) 
Advise WM_DDE_ACK (2) WM_DDE_ACK (1) 
Unadvise WM_DDE_ACK (2) WM_DDE_ACK (1) 
Pike WM_DDE_ACK (2) WM_DDE_ACK (1) 
Execute WM_DDE_ACK (2) WM_DDE_ACK (1) 
Terminate WM_DDE_TERMINATE (3) 


(1) DDE_FACK not present in fsStatus field of DDESTRUCT structure. 
(2) DDE_FACK present in fsStatus field of DDESTRUCT structure. 
(3) No negative respinse is defined for the Terminate transaction. 
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compatibility. For example, if data is being exchanged between a 16-bit 
and 32-bit application, the receiving application would have to (1) be 
aware of the presence of the pointer or handle, and (2) do the appropri- 
ate conversion from 16-bit to 32-bit, or vice versa. 

Moreover, with the release of the OS/2 operating system (version 2.0), 
it is possible to exchange data between PM and Windows applications. 
This creates the additional restriction of embedded handles and point- 
ers since they have no meaning outside the session in which they were 
created. 

The OS/2 components responsible for providing DDE communications 
between Windows and PM sessions can only translate standard DDE 
formats (for example, translating a PM bitmap to a Windows bitmap). 
This is possible because the content of the data portion is in a docu- 
mented format. For non-standard (private) formats, the contents of the 
data portion are unknown and the data are passed “as is.” 


MESSAGE SYNCHRONIZATION 


All DDE messages related to a specific conversation link must be proc- 
essed strictly in the order they were received. For example, a DDE 
application might have the following messages in its message queue: 


Message #1 from window x 
Message #2 from window y 
Message #3 from window x 


In this example, message 1 and message 3 originated from the same 
window. Therefore, the receiving application must process message 1 
before message 3, but it does not need to process message 2 before 
message 3. However, this first-in, first-out (FIFO) rule only applies to 
messages originating from the same window. Given this rule, an appli- 
cation can give one conversation link priority over another. By using the 
WinPeekMsg API, an application can examine its message queue and 
extract those messages it determines to have the greater priority. 

Caution: After retrieving a message using the WinPeekMsg API, no 
attempt to reference message parameter one (mp1) or two (mp2) should 
be made. An application should, instead, dispatch the message using the 
WinDispatchMsg API, where it is processed in its corresponding win- 
dow procedure. This step is necessary to ensure compatibility between 
applications of different memory models. 

Messages are placed in an application queue in the memory model in 
which they originated; that is, a message from a 32-bit application 
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would be in 32-bit format and a message from a 16-bit application 
would be in 16-bit format. (Format implies that pointers are either in 
16:16 segmented or 0:32 flat format.) Therefore, it is possible that a 
16-bit application could retrieve a message in 32-bit format and vice 
versa (for example, a 16-bit client was communicating with a 32-bit 
server). PM delays the thunking until the message is dispatched to a 
window procedure. 

Since most DDE messages contain a pointer to a DDEINIT or DDE- 
STRUCT structure in message parameter two (mp2), a DDE applica- 
tion implementing this type of message-handling must either dispatch 
the message and let PM do the thunking or thunk the pointer manually 
before referencing it. (A thunk is a mapping technique used to convert 
16-bit references to 32-bit references, or 32-bit to 16-bit. A complete 
explanation of thunking is beyond the scope of this book.) Failure to 
handle this condition will cause an exception in the application by the 
OS/2 operating system. 


Once a conversation link has been established, a client can request that 
the server provide a data item on demand. A server provides the data 
item once per request. This one-time data transfer is commonly known 
as a cold link. Figure 4-1 illustrates a simplified successful transaction 
sequence. 


Client Server 


Give me a data item. 


WinDdePostMsg ( ) WM_DDE REQUEST Ok, here it is. 


Thanks, fy it. <RDETE DDE_ DATA WinDdePostMsg ( ) 
a ma 


Figure 4-1. Message Flow: DDE Request (Cold-link) 


Guidelines 
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Typically, a Request transaction is issued as the result of some user 
action requesting a piece of information from a server. To this extent, 
the Request transaction is not unlike clipboard transactions. Another 
common use for the Request transaction is to obtain a data item after 
an application has been notified that it has changed. This type of 
notification is called a warm-link and is discussed later in this sec- 
tion. 

A client application requests a data item by allocating a shared 
memory object and posting a WM_DDE_REQUEST message to a 
server application. To simplify this process, the function DdeRe- 
questColdLink can be called and is shown in Listing 4-1. Con- 
versely and somewhat more complicated, the processing of a 
WM_DDE_REQUEST message is illustrated by the DdeConvWm- 
DdeRequest function shown in Listing 4-2. 


= The presence and interpretation of status flags are unde- 
fined for this transaction. In addition, the contents of the 
data portion are also unspecified, that is, it is physically 
possible to include data along with the request. However, 
how this data is interpreted is application specific. 


38 «In the Windows implementation of the DDE protocol, this 
message does not allow for defining status flags. This field is 
ignored when passing this message to a application running 
in a WIN-OS2 session. 


38 «In the Windows implementation of the DDE protocol, this 
message does not contain a data portion. If specified by a PM 
application, the data is ignored and discarded when posting 
this message to a application running in a WIN-OS2 session.. 


A client application must: 


=» Allocate a shared memory object large enough to contain a 
DDESTRUCT structure. 

= Specify the requested data item name and format identifier, 
indicating the layout of the rendered data item. 
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_ 

*K* 

ee FUNCTION: DdeRequestColdLink 

K* 

es |JSage; Requests a data item from a DDE ‘Server’ window. 

*K* 

a Se SS ee SS SS ea ee * / 
BOOL f* TResult: Suceess indicator od 
APIENTRY DdeRequestColdLink 

( 

HWND hwndServer /* desired server window handle m 
HWND hwndClient /* requesting window handle my 
PZ pszItemName /* desired item name-string * 

, USHORT usFormat /* desired format = 

) 

{ 

BOOL fResult = FALSE; 
PDDESTRUCT pDdeStruct = NULL; 

i * 

** Creates a DDE shared memory object... 

me 
pDdeStruct = DdeMakeDdeStruct /* create a shared memory object a | 

( pszItemName /* null (0x00) terminated ASCII string * | 
, NULL /* pointer to data (not applicable) wf 
_ OL /* size of data (in bytes) salt 
, usFormat /* registered DDE format identifier a | 
« 2 /* DDE status flags (not applicable) st 
3 

/ * 

**x If shared memory object successfully created... 

= 
if (pDdeStruct) 

{ 
fResult = WinDdePostMsg /* post a DDE message to... ai | 
( hwndServer j* this requesting window handle, a 
, hwndClient fe from this responding window handle, */ 
, WM_DDE_REQUEST ‘ies a “Request” message, ~y 
, pDdeStruct /* as defined in this memory object, Fs 
, DDEPM_RETRY es and retry if receiving queue is full.*/ 


I; 
} 
return (fResult); 
} 


Listing 4-1. Client: Issue WM_DDE_REQUEST 


/* 


K* 


ay 


Function: 


Usage: 


Remarks: 


Guidelines: 


1) 


2) 


MRESULT 
APTENTRY 


HWND 
MPARAM 
MPARAM 


BOOL 
BOOL 
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DdeConvWmDdeRequest 


Processes a “WM_DDE_REQUEST” message dispatched to a “WC_DdeConv” 
class window. 


The WM_DDE_REQUEST message is posted by a client application to 
request that a server application provide a data item rendered 
in the specified format. This type of a request is commonly 
known as a “Cold Link”. 


Any message posted in response should be to the window handle 
Specified in message parameter one (mpl). 


If the server is able to satisfy the request, it acknowledges 
the request by responding with a WM_DDE_DATA message containing 
the rendered data item. If the server is unable to satisfy the 
request, it responds with a negative WM_DDE_ACK message. 


Status flags are undefined in the context of this message. If 
present, their meaning is not defined by the protocol. 


== ee ee ee ee ee ee ee ee ee SS SS SS SS SS SS SK j 
/* flReply: Reserved value, zero (0) my 

DdeConvWmDdeRequest 

hwnd /* handle of window receiving message */ 

mp1 /* originator window handle xf 

mp2 /* pointer to a BDESTRUCT structure a | 

fCaseSensitive = FALSE 

FResult = FALSE 


Obtain and set DDE transaction information... 


HWND 
PDDESTRUCT 
Pod 

USHORT 
USHORT 
HWND 


hwndClient = HWNDFROMMP (mpl); 
pDdeStruct = (PDDESTRUCT) PVOIDFROMMP (mp2); 
pszItemName = DDES_PSZITEMNAME (pDdeStruct) ; 


usFormat = pDdeStruct->usFormat; 
usCodepage = ConvContext.usCodepage; 
hwnditem = NULLHANDLE; 


Obtain “WC _DdeConv” window class info... 


Listing 4-2. Server: Process WM_DDE REQUEST 
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/* 
xK* 
RX 


a 


/* 


Kx 


ny 


/* 


*K* 


a 


if (pDdeStruct) 


fResult 


( 
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PCONVINFO pConvInfo = (PCONVINFO) WinQueryWindowPtr 
( hwnd 
, OQWL_USER 
rs 
Insert message and associated information into listbox. 
Note: Typically, an application receiving a DDE message will free the 
associated shared memory object after processing this message (as 
Shown at the end of this function. However, we save the original 
Shared memory object for subsequent retrieval by the user. The 
Shared memory object is freed when the listbox is destroyed or 
cleared. 
SHORT SIltemIndex = FrminsertListboxItem 
( hwndListBox 
, WM_DDE_REQUEST 
ulMsglime 
, (ULONG) pDdeStruct 
ie 
If the server application is busy, respond with a negative WM_DDE_ACK 
message indicating this state. 
if (pConvinfo->fsState & CONVINFO_State_Busy) 
Create a DDE shared memory object... 
pDdeStruct = DdeMakeDdeStruct 
( pszItemName /* item name-string 
, NULL /* pointer to data (not applicable) 
» OL /* size of data (not applicable) 
usFormat | /* requested format identifier 
, DDE_FBUSY /*® Status Tlads 
)3 
If shared memory object successfully created... 


WinDdePostMsg /* post a DDE message to... 


hwndClient ig 
, hwnd fR 
, WM_DDE_ACK -= 
pDdeStruct j* 
DDEPM_RETRY re 


Listing 4-2. 


this requesting window handle, 

from the “Conv” window handle, 

an “Acknowledgement” message, 

as defined in this memory object, 

and retry if receiving queue is full. 


(continued) 


| 
a i 
as 
hd 
al 
sa 


/* 


xk* 


ar 5 


K* 


Kx 


mf 
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If *pest” failed... 


if (fResult == FALSE) 
| 
DosFreeMem (pDdeStruct);/* free the shared memory object. * / 
} 
} 


The receiver of a DDE message is responsible for the memory object 
associated with a DDE message. The receiver must either reuse or free 
the memory object. The example programs retain the original memory 
object for subsequent retrieval. The following statement would normally 
be executed at this point and is shown here for completeness. 


DosFreeMem (PVOIDFROMMP (mp2)); 


return (MRFROMSHORT (0)); 


If a conversation context is associated with this conversation, 
determine context specific information... 


if (pConvinfo->pConvContext) 


Determine if string comparisons are case-sensitive. By default, 
all strings comparisons are not case-sensitive. 


if (pConvinfo->pConvContext->fsContext & DDECTXT_CASESENSITIVE) 
fCaseSensitive = TRUE; 


Determine the codepage the requesting application is using. 

This is used to translate strings before comparisons are made. If 
the requesting application is using a different codepage than this 
application, then strings are first translated to the codepage in use 
by this application. 


usCodepage = pConvIinfo->pConvContext->usCodepage; 


Query corresponding *Item’ window... 


hwndiItem = DdeQueryltemWindow 


( WinQueryWindow (hwnd, QW_PARENT ) 
DDES_PSZITEMNAME (pDdeStruct) 


Listing 4-2. (continued) 
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/* 


kK* 


= 


/* 


Kx 


* if 


/* 


kK* 


ot | 


/* 


K* 


at | 


/* 


Kx 


ny 


If 


ei 
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, usCodepage 

, fCaseSensitive 

, BMSG_DESCENDANTS 
); 


"ITtem’ window found... 
(hwndItem) 


pDdeStruct = (PDDESTRUCT) WinSendMsg 
( hwndItem 
, UM_RenderlItem 
, MPFROM2SHORT (usFormat, DDE_FRESPONSE) 
, MPVOID 
if 


If data item successfully rendered, respond to requesting application... 


if (pDdeStruct) 


fResult = WinDdePostMsg /* post a DDE message to... 
( hwndClient /* this requesting window handle, 
, hwnd — from the “Conv” window handle, 
, WM_DDE_DATA [* an “Data” message, 
, pDdeStruct hg as defined in this memory object, 
, DDEPM_RETRY {= and retry if receiving queue is full. 


js 
If ‘post’ failed... 
if (fResult == FALSE) 
{ 


DosFreeMem (pDdeStruct);/* free shared memory object 


request failed... 


(fResult == FALSE) 


Create a DDE shared memory object... 


pDdeStruct = DdeMakeDdeStruct 


( pszItemName /* item name-string 
, NULL /* pointer to data (not applicable) 
5 /* size of data (not applicable) 


Listing 4-2. (continued) 


| 


ae | 
* 
LF | 


/* 


xK* 


a7 


/* 


K* 


a 
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usFormat /* DDE format identifier * | 
. 0 /* DDE Status Flags * 
is 


If shared memory object successfully created... 


if (pDdeStruct) 


fResult = WinDdePostMsg /* post a DDE message to... © f 
( hwndClient /* this requesting window handle, mf 
, hwnd ps from the “Conv” window handle, a | 
, WM_DDE_ACK {* an “Acknowledgement” message, a 
, pDdeStruct al as defined in this memory object, ae 


, DDEPM_RETRY /[* and retry if receiving queue is full.*/ 
iF 


If *post’ failed, free memory object... 


if (fResult == FALSE) 
DosFreeMem (pDdeStruct) ; 


The receiver of a DDE message is responsible for the memory object 
associated with a DDE message. The receiver must either reuse or free 
the memory object. The example programs retain the original memory 
object for subsequent retrieval. The following statement would normally 
be executed at this point and is shown here for completeness. 


DosFreeMem (PVOIDFROMMP (mp2)); 


return (MRFROMSHORT (0)); 


Listing 4-2. (continued) 


A server application must: 


= Respond to the window handle specified in message parame- 
ter one (mp1). 

a Free or reuse the shared memory object containing the 
DDESTRUCT structure. 

= Render the data item in a WM_DDE_DATA message in the 
requested format, or respond with a _ negative 
WM_DDE_ACK message. 


38 DYNAMIC DATA EXCHANGE FOR 0S/2 PROGRAMMERS 


ADVISE 


A client application can request that it be advised each time a data item 
changes. This frees a client application (and its user) from having to 
determine if and when a data item has changed, and then requesting it. 

If the server is able to satisfy the request, it acknowledges the request 
by responding with a WM_DDE_ACK message and establishes a per- 
manent data-link between the two applications. If the server is unable 
to satisfy the request, it responds with a negative WM_DDE_ ACK 
message. Figure 4-2 illustrates a simplified and successful Advise (hot- 
link) transaction. 

Once such a link is established, the server advises the client applica- 
tion, when the data item changes, by posting a WM_DDE_DATA mes- 
sage. A client application continues to receive WM DDE DATA 
messages until either the data-link or the conversation link is termi- 
nated. This type of data-link is commonly known as a hot-link and is 
ideal if the data item can be rendered quickly. Listing 4-3 shows how a 
hot-link request is issued. 


Client Server 


Give me a data item 
when it changes. 


V 


WinDdePostMsg() | |WM DDE ADVISE Ok, I will. 


(Sometime Later) 


It changed, here it is. 


V 


Thanks, got it. WM_DDE_DATA WinDdePostMsg ( ) 


V 


WinDdePostMsg ( ) 


Figure 4-2. Message Flow: DDE Advise (Hot-link) 


K* 


a | 


/* 


Kx 


ai 3 
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Function: 


Usage: 


BOOL 
APIENTRY 


HWND 
HWND 
PSZ 
USHORT 


BOOL 
PDDESTRUCT 


Creates a DDE 


pDdeStruct 


DdeRequestHotLink 


Requests that a permanent data-link be established with the 
specified ’Server’ window, and that the ’Server’ post data 
in the resulting WM_DDE_DATA messages. 


DdeRequestHotLink 


hwndServer 
hwndClient 
pszItemName 
usFormat 


fResult = FALSE; 


pDdeStruct = NULL; 


= DdeMakeDdeStruct 
( pszltemName 

» NULL 

, OL 

, usFormat 

, DDE_FACKREQ 

i 


/* 


fResult: Success indicator 


desired server window handle 
requesting window handle 
desired item name-string 
desired format 


Shared memory object... 


create a shared memory object 

null (0x00) terminated ASCII string 

pointer to data (not applicable) 

Size of data (in bytes) 

registered DDE format identifier 

set DDE_FACKREQ status flag in 
Subsequent WM_DDE_DATA messages 


If shared memory object successfully created... 


if (pDdeStruct) 


fResult 


= WinDdePostMsg 
( hwndServer 

, hwndClient 

, WM_DDE_ADVISE 
, pDdeStruct 

, DDEPM_RETRY 
ie 


return (fResult); 


/* 
/* 
/* 


post a DDE message to... 
this requesting window handle, 


from this responding window handle, 


a “Advise” message, 
as defined in this memory object, 


and retry if receiving queue is full. 


Listing 4-3. Client: Issue WM_DDE_ADVISE (Hot-link) 
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The WM_DDE_DATA message contains the data item rendered in 
the format specified in the initial advise request. The cbData of the 
DDESTRUCT structure is set to the length of the data only. If it takes 
a significant amount of time to render the data item, or the data item 
changes frequently, a client application can request it be notified rather 
than updated with the data item each time it changes. A client is 
notified with a WM_DDE_DATA message, just like an update; however, 
the WM_DDE_DATA message contains no data. This type of data-link 
is commonly known as a warm-link (see Figure 4-3). 

A client application requests notification by setting the DDE_FNO- 
DATA status flag when issuing the advise request, as shown in Listing 
4-4. If set, the server does not render the data-item, rather it simply 
posts a WM_DDE_DATA message with zero (0) bytes of data and the 
DDE_FNODATA status flag set. 

Upon receiving such a notification, the client application can either 
ignore it or request the data item by performing a one-time 
(WM_DDE_REQUEST) Request transaction. 

If a data item changes frequently, it is possible that the client’s 
message queue could be filled with WM_DDE_DATA messages faster 
than the client can process them. To prevent this condition from occur- 
ring, the DDE protocol provides a form of flow-control whereby the 
client can control the rate at which WM_DDE_DATA messages are 
received. To accomplish this, the client application can set the 
DDE_FACKREQ status flag in the initial advise request. 

If the DDE_FACKREQ status flag is set in a WM_DDE_ADVISE 
request, the receiving application is required to set the DDE_FACKREQ 
status flag on subsequent WM_DDE_DATA messages corresponding to 
the request. Upon issuing a WM_DDE_DATA message with the 
DDE_FACKREQ status flag set, the responding application waits until 
it has received a WM_DDE_ACK message in response, prior to posting 
a subsequent WM_DDE_DATA message. 

It is legal for a client application to request a data item in which it 
already has an active data-link established. This is how a client obtains 
the data item in response to a warm-link notification, as mentioned 
previously. An advise request for a data item in which the requesting 
client is currently engaged in a data-link is interpreted as follows: 


1. Ifthe request is for a format other than one currently estab- 
lished, then the request is interpreted as a new request and 
a data-link is created. 

2. If the request is for a format for which a data-link already 
exists, the server responds positively to the request, but no 
new link is established. 
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Client Server 


Notify me when a 
data item changes. 


WinDdePostMsg ( ) WM_DDE_ ADVISE Ok, I will. 


WinDdePostMsg (_ 


(Sometime Later) 
It changed. 


WM_DDE_DATA (No Data) WinDdePostMsg (_ 


(sometime later) 
Ok, give me the data now. 


V 


WinDdePostMsg ( ) WM_DDE_ REQUEST Ok, here it is. 


V 


Thanks, got it. WM_DDE_ DATA WinDdePostMsg (_ 


WinDdePostMssg ( ) 


Figure 4-3. Message Flow: DDE Advise (Warm-link) 


Therefore, it is possible that multiple data-links exist for the same 
topic/data item pair, but for different formats; for example, one for 
bitmap, one for text and one for metafile. 

The functions in Listing 4-5 show the processing routines use by the 
example server application to process the WM_DDE_ADVISE request. 
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/ kaeeee aaa aaa SaaS SSS SSS SS SS SS SSS SSS SSS SS SSS SSS SSS SSS SSS SSS SSS SSS SSS SSS SSS 

*K* 

ee Function: DdeRequestWarmLink 

K* 

“* Usage: Requests that a permanent data-link be established with the 

we specified ’Server’ window, and that the ’Server’ post no data 

she in the resulting WM_DDE_DATA messages. 

*K* 

a a a if 
BOOL /* fResult: Success indicator ae | 
APIENTRY DdeRequestWarmLink 

( 

HWND hwndServer /* desired server window handle * J 

HWND hwndClient /* requesting window handle * 

Pee: pszltemName /* desired item name-string od 4 
, USHORT usFormat /* desired format my 
) 

BOOL fResult = FALSE; 

PODESTRUCT pDdeStruct = NULL; 

/* 

** Creates a DDE shared memory object... 

Ly 
pDdeStruct = DdeMakeDdeStruct /* create a shared memory object al 

( pszItemName /* null (0x00) terminated ASCII string ad 5 
» NULL /* pointer to data (not applicable) a | 
, OL /* size of data (in bytes) sal 
, usFormat /* registered DDE format identifier ald 
, DDE_FNODATA /* send no data in updates oF | 
| DDE_FACKREQ /* set DDE_FACKREQ status flag in ad | 
1 {* subsequent WM_DDE_DATA messages * / 

/* 

*k If shared memory object successfully created... 

a 5 
if (pDdeStruct) 

{ 
fResult = WinDdePostMsg /* post a DDE méssagée to... ak | 
( hwndServer j* this requesting window handle, =f 
» hwndClient je from this responding window handle, */ 
, WM_DDE_ADVISE j* a “UnAdvise” message, sal 
, pDdeStruct hg as defined in this memory object, a | 
, DDEPM_RETRY f= and retry if receiving queue is full.*/ 


ys 
} 
return (fResult); 
} 


Listing 4-4. Client: Issue WM_DDE_ADVISE (Warm-link) 
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As illustrated, the function basically checks if it currently supports the 
requested item and format. If it does, it creates a WC_DdeAdvise class 
window to support the data-link and responds with a positive 
WM_DDE_ACK message; otherwise it responds with a negative 
WM_DDE_ACK message. A WC_DdeAdvise class window maintains 
information about the original WM_DDE_ADVISE request. When the 
server application has determined that a data item has changed, it 
broadcasts an UM_DdeAdvise message to each of these windows, which 
is responsible for updating or notifying the original requesting applica- 
tion. The function shown in Listing 4-6 is called by a WC_DdeAdvise 
class window to process the UM_Adviseltem message. 


FUNCT ON: 


Usage: 


Remarks: 


Guidelines: 


1) 


2) 


3) 


4) 


D ) 


DdeConvWmDdeAdvise 


Processes a “WM_DDE_ADVISE” message dispatched to a “WC_DdeConv” 
class window. 


The WM_DDE_ADVISE message is posted by a client application to 
request that a server application update or notify it each time 
the specified data item changes. 


Any message posted in response should be to the window handle 
specified in message parameter one (mpl). 


If the server is able to satisfy the request, it acknowledges 
the request by responding with a positive WM_DDE_ACK message and 
establishes a permanent data-link between the two applications. 
If the server is unable to satisfy the request, it responds with 
a negative WM_DDE_ACK message. 


Once such a link is established, the server advises the 
requesting application when the data item changes by posting a 
WM_DDE_DATA message. 


The WM_DDE_DATA message may or may not contain the updated data 
item. Subsequent WM_DDE_DATA messages contain data depending on 
the status flag of the original WM_DDE_ADVISE message. If the 
DDE_FNODATA status flag was set, subsequent WM_DDE_DATA messages 
contain no data. This type of a data-link is commonly known as 
a “warm-link”. 


Upon receiving a (warm-link) notification, the client application 


Listing 4-5. Server: Process WM DDE ADVISE 
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6 ) 


/) 


8) 


MRESULT 
EXPENTRY 


HWND 
MPARAM 
MPARAM 


BOOL 
BOOL 


can either ignore the notification, or request the data item by 
performing a one-time (WM_DDE_REQUEST) request transaction. 


If the DDE_FNODATA status flag was not set, subsequent 

WM DDE_DATA messages contain the rendered data item in the format 
specified in the original WM_DDE_ADVISE message. This type of 
data-link 1s commonly known as a “hot-link”. 


If the DDE_FACKREQ status flag was set on the original 
WM_DDE_ADVISE request, a server is required to set the 
DDE_FACKREQ status flag on subsequent WM_DDE_DATA messages. 

In addition, the server agrees not to post any subsequent 
WM_DDE_DATA messages until the client application has responded 
with a WM_DDE_ACK message. 


This offers a form of flow control whereby the client application 
can control the rate at which it receives WM_DDE_DATA messages. 
This prevents the client’s message queue from being flooded with 
messages quicker than it can process them. 


It is legal for a client application to request a data item in 
which it already has an active data-link. An advise request for 
a data item in which the requesting client is currently engaged 
in a data-link is interpreted as follows: 


a) If the request if for a format other than those currently 
established, then the request is interpreted as a new request 
and a new data-link is created. 


b) If the request is for a format for which a data-link already 
exists, the servers responds positively to the request, but 
no new link is established. 


= eS ESS SS K / 
/* flReply: Reserved value, zero (0) cam | 

DdeConvWmDdeAdvise 
hwnd /* handle of window receiving message = 
mp1 /* handle of window originating message mf 
mp2 /* pointer to DDESTRUCT structure ee 


fCaseSensitive = FALSE; 
fResult = FALSE: 


Obtain window handle of requesting application... 


HWND 
HWND 


hwndClient = HWNDFROMMP (mpl); 
hwndItem NULLHANDLE; 


Listing 4-5. (continued) 


/* 


Kx 


/* 
K* 
kK* 


at 


/* 


K* 


ne 
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Query pointer to “WC_DdeAdvise” class information... 


PCONVINFO pConviInfo (PCONVINFO) WinQueryWindowPtr 
( hwnd 


QWL_USER 


Obtain pointer to shared memory object containing DDESTRUCT structure, 
and extract the DDE format and Item name being requested... 


PDDESTRUCT pDdeStruct = (PDDESTRUCT) PVOIDFROMMP (mp2); 
PSZ pszItemName = DDES_PSZITEMNAME (pDdeStruct) ; 
USHORT TSStatus = 0; 

USHORT usFormat = pDdeStruct->usFormat; 

Set default codepage for string comparisons... 

USHORT usCodepage = ConvContext.usCodepage; 

Insert message and associated information into listbox. 


Note: Typically, an application receiving a DDE message will free the 
associated shared memory object after processing this message (as 


Shown at the end of this function. However, we save the original 
Shared memory object for subsequent retrieval by the user. The 
Shared memory object is freed when the listbox is destroyed or 
cleared. 
SHORT sItemIndex = FrminsertListboxItem 

( hwndListBox 

, WM_DDE_ADVISE 

, UulMsgTime 

, (ULONG) pDdeStruct 

e 


If the server application is busy, respond with a negative WM_DDE_ACK 
message indicating this state. 


if (pConvinfo->fsstate & CONVINFO_State_Busy) 


Create a DDE shared memory object... 


pDdeStruct = DdeMakeDdeStruct 


( pszItemName /* jtem name-string 

, NULL /* pointer to data (not applicable) 
ATE /* size of data (not applicable) 

, usFormat /* registered DDE format identifier 


Listing 4-5. (continued) 
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~ i 


/* 


*K* 


ey 


/* 


x* 
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}; 


If shared memory object was successfully allocated... 


if (pDdeStruct) 


fResult = WinDdePostMsg 
( hwndClient ;* 
, hwnd 
, WM_DDE_ACK ;* 
, pDdeStruct ihe 
, DDEPM_RETRY ;* 


py 


If posting of the WM_DDE_ACK DDE message failed... 


, DDE_FBUSY 


J/* DDE status flags 


/* post a DDE message to... 
this requesting window handle, 


/* from the “Advise” window handle, 


if (fResult == FALSE) 


an “Acknowledgement” message, 
as defined in this memory object, 
and retry if receiving queue is full. 


DosFreeMem (pDdeStruct); /* free shared memory object 


The receiver of a DDE message is responsible for the memory object 


associated with a DDE message. 


the memory object. 


object for subsequent retrieval. 


The receiver must either reuse or free 


The example programs retain the original memory 


The following statement would normally 


be executed at this point and is shown here for completeness. 


DosFreeMem (PVOIDFROMMP (mp2)); 


return (MRFROMSHORT (0)); 


If a conversation context is associated with this conversation, 


context specific information... 


if (pConvInfo->pConvContext) 


Determine if string comparisons are case-sensitive. 


Strings comparisons are not case-sensitive. 


determine 


By default, all 


if (pConviInfo->pConvContext->fsContext & DDECTXT_CASESENSITIVE) 


{ 
fCaseSensitive 
} 


TRUE: 


Determine the codepage the requesting application is communicating in. 
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ay 


a 


/* 


*K* 


a | 


/* 
xK* 
kK* 


af 


/* 
K* 
K* 
k* 
*K* 


ad 
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this is used to translate strings before comparisons are made. If 
the requesting application is using a different codepage than this 
application, then strings are first translated to the codepage in use 
by this application. 


usCodepage 


Find corresponding item window by searching each descendant of our parent. 
The parent of a conversation window (a topic window) is also the parent of 


= pConvInfo->pConvContext->usCodepage; 


any item that might be requested by a conversation. Ihe architecture of 


these example 


programs guarantee this relationship. 


hwndItem = DdeQueryItemWindow 
( WinQueryWindow (hwnd, QW_PARENT ) 
, DDES_PSZITEMNAME (pDdeStruct) 
, usCodepage 
, fCaseSensitive 
, BMSG_DESCENDANTS 


ys; 
If a matching 


if (hwndItem) 
{ 


item window was found... 


CONVID Convlid; 


Convild.hwndServer 


hwnd; /* identify responding window handle 


Convild.hwndClient = hwndClient; /* identify requesting window handle 


Send a WM_DDE_ADVISE message to the item window. Upon receipt of this 


Messaye an 


fResult = 
( 


item window will create a data-link (Advise) window. 


(BOOL) WinSendMsg 
hwndItem /* jtem window handle 
WM _DDE_ADVISE /* re-use same message identifier 


, MPFROMP (&ConviId) /* pointer to CONVID structure 


mp2 /* pointer to DDESTRUCT structure 


If “fResult’ is TRUE at this point, then the WM_DDE_ADVISE message has 
Successfully been processed and we respond with a positive WM_DDE_ACK 


message. If ’fResult’ is FALSE, then an error occurred and we respond with 
a negative WM_ 


fsStatus = 
* 


DDE_ACK message. 


(fResult) 
DDE_FACK /* positive acknowledgement 
Q; /* negative acknowledgement 
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/* 
** Create a DDE shared memory object... 
ad | 
pDdeStruct = DdeMakeDdeStruct 
( pszIltemName 


, NULL /* pointer to data (not applicable) salt 
, BL /*® zero (no data) ef 
, usFormat /* registered DDE format identifier sa 
, tS5batus J/* DDE status flags call 
i: 
/* 
** If shared memory object successfully created... 
mf 
if (pDdeStruct) 
{ 
fResult = WinDdePostMsg /* post a DDE message to... iF 
( hwndClient j* this requesting window handle, * f 
, hwnd fs from the “Advise” window handle, at J 
, WM_DDE_ACK ya an “Acknowledgement” message, sa 
, pDdeStruct fe as defined in this memory object, alt | 
DDEPM_RETRY f% and retry if receiving queue is full.*/ 


** The receiver of a DDE message is responsible for the memory object 

** associated with a DDE message. The receiver must either reuse or free 
** the memory object. The example programs retain the original memory 

** object for subsequent retrieval. The following statement would normally 
** be executed at this point and is shown here for completeness. 


ke DosFreeMem (PVOIDFROMMP (mp2)); 


return (MRFROMSHORT (0)); 


| K§eeee sana a sen aa eee eae a See a Sa ee a Ses SS SSS SSS SSS SS SS SS SSS SS SSS SSS SSS SSS SSS SS SEs 

kK* 

we FURCT ION § DdeltemWmDdeAdvise 

kK* 

** Usage: Processes a “WM_DDE_ADVISE” message dispatched to a “WC_Dde_Item” 

a class window. 

K* 

** Remarks: A “WM _DDE_ADVISE” message is sent by a “WC_DdeConv” class window 

ial after it has accepted the ’Advise’ request. Upon receipt of this 

ai message, a “WC _DdeAdvise” class window will be created to 

we Support the requested ’data-link’. 

K* 

= SS SSS SS SSS SSS SS SSS SS SS SS SS SS SS SS SSS SSS / 
MRESULT 
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APIENTRY DdeItemWmDdeAdvise 


HWND hwnd 
MPARAM mp1 
MPARAM mp2 


/* handle of window receiving message 
/* pointer to CONVID structure 
/* pointer to DDESTRUCT structure 


Obtain a pointer to the DDESTRUCT structure specified in the request... 


PDDESTRUCT pDdeStruct 


Obtain the handle of a 


= (PDDESTRULT) PYOIDFROMMP (mpc); 


“WC_DdeAdvise” class window (if any) currently 


Supporting this format... 


HWND hwndAdvise 


WinWindowFromI!D 

( hwnd 

, pDdeStruct->usFormat 
it 


[If no “Gata-link’ currently G@xISts.... 
if (hwndAdvise == NULLHANDLE) 
Obtain “WC_DdeItem” window class info... 
PDDEITEM pDdeItem = (PDDEITEM) WinQueryWindowPtr 
( hwnd 
, QWL_USER 
ie 
Create a “WC _DdeAdvise” class window... 
hwndAdvise = DdeCreateAdviseWindow 
( hwnd /* parent window handle 
, hwnd /* owner window handle 
, (PCONVID) PVOIDFROMMP (mpl) /* ’Conversation Information’ 
, PRCESTPUET-ATSStatus /* original DDE status flags 
, pDdeStruct->usFormat /* DDE format identifier 
i 
Return *’TRUE’ if “WC _DdeAdvise” class window created, otherwise return 
“FALSE. 


return MRFROMSHORT ((hwndAdvise) ? TRUE : FALSE); 
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FUNCT TON: DdeAdviseUmAdviseltem 
Usage: Processes a “UM_AdviseItem” dispatched to a “WC_DdeAdvise” class 
window. 
Remarks: A “UM_AdviseItem” message is issued by a DDE server application 
to all of its “WC_DdeTopic” class windows. A “WC_DdeTopic” 
class window issues the ’same’ message to of its (WC_Ddeltem) 
children windows. A “WC_Ddeltem” window determines if the 
"Advise’ notification corresponds to the ’Item’ it is supporting. 
If it is, it broadcasts the message to all of its (WC_DdeAdvise) 
children windows. 
MRESULT /* fResult (BOOL): Error indicator ay 
EXPENTRY DdeAdviseUmAdviseltem 
HWND hwnd /* handle of window receiving message sal 
MPARAM mp1 /* item identifier ial | 
MPARAM mp2 /* item handle (hwndMenu, pszText or Time)*/ 
BOOL FResult = PALES 
PDDESTRUCT pDdeStruct; 
Query pointer to “WC_DdeAdvise” class information... 
PDDEADVISE pDdeAdvise = (PDDEADVISE) WinQueryWindowPtr 
( hwnd 
, QWL_USER 
i 


Obtain the associated DDE format identifier by querying the window 


identifier of the “WC_DdeAdvise” class window. Windows of this class 
Set their window identifier equal to the format it is Supporting. 
USHORT usFormat = (USHORT) WinQueryWindowUShort 

( hwnd 

y3 


If this data-link is currently waiting for a WM_DDE_ACK message in response 
to a previous request, ignore discard the update notification. 


Listing 4-6. Server: Process UM_Adviseltem 
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if (pDdeAdvise->fAckPending == TRUE) 
return (MRFROMSHORT (FALSE)); 
/* 
** ASk our owner to render the data item in the requested format, 
cat | 
pDdeStruct = (PDDESTRUCT) WinSendMsg 
( WinQueryWindow (hwnd, QW_OWNER) 
, UM_RenderItem 
, MPFROM2SHORT (usFormat, pDdeAdvise->fsStatus) 


» Mp2 

Ms 
/* 
** If our owner successfully rendered the item... 
se 


if (pDdeStruct) 
HWND hwndClient = pDdeAdvise->hwndClient; 


/* 

ial Notify client application that the data item changed... 

* 

fResult = WinDdePostMsg /* post a DDE message to... =] 

( hwndClient /* this requesting window handle, */ 
, hwnd fs from the “Advise” window handle, ia | 
, WM_DDE_DATA oe a “Data” message, a | 
, pDdeStruct {% as defined in this memory object ai 
, DDEPM_RETRY f* and retry if receiving queue is full.*/ 
ye 

/* 

wR If message was successfully posted, set the fAckPending (control-flow) 

did flag according to value specified in the original WM_DDE_ADVISE message. 

we Otherwise, we failed and need to free any allocated resources. 

ae J 


if (fResult) 
| pDdeAdvise->fAckPending = (pDdeAdvise->fsStatus & DDE_FACKREQ) ; 
ee 
| DosFreeMem (pDdeStruct) ; 
| 


return MRFROMSHORT (fResult); 


Listing 4-6. (continued) 
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A client application must: 


Allocate a shared memory object large enough to contain a 
DDESTRUCT structure. 

Specify the requested data item name and format identifier 
indicating the desired layout of the rendered data item. 
Specify whether or not subsequent WM_DDE_DATA mes- 
sages contain the rendered data item (a hot-link), or no data 
(a warm-link). 

Specify whether or not the server should set the 
DDE_FACKREQ status flag on subsequent 
WM_DDE_DATA messages. 

Process the WM_DDE_ACK message posted in response to 
this request. The client application must determine if the 
Advise request was accepted. How the client application 
handles a positive or negative response is application-spe- 
cific. 


A server application must: 


Respond to the window handle specified in message parame- 
ter one (mp1). 

Free or reuse the shared memory object containing the 
DDESTRUCT structure. A server can reuse the memory 
object when responding with a negative WM_DDE_ ACK 
message, rather than freeing one and creating another. 
Respond with either a positive or negative WM_DDE_ACK 
message. 

Honor the DDE_FNODATA and/or the DDE_FACKREQ 
status flags, if set. 

If the data item is not available at the time of the request, 
the server is not obligated to render the data item when it 
does become available. 


The Unadvise transaction is posted by a client application to terminate 
a previously-established (WM_DDE_ADVISE) data-link. Upon receipt 
of a WM_DDE_UNADVISE message, the server determines if the re- 
questing client currently has a data-link established. If it does, the 
server terminates the data-link and posts a positive WM_DDE_ACK 
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message in response. If it does not, the server posts a negative 
WM_DDE_ACK message. Figure 4-4 illustrates a simplified and suc- 
cessful Unadvise transaction. 

It is possible that a client has established more than one data-link 
with a server. If a client application has multiple data-links estab- 
lished, it does not need to terminate each individual data-link sepa- 
rately; that is, a client can terminate one or more data-links with a 
single WM_DDE_UNADVISE message. 

The contents of usFormat and the presence of a data item name 
determines the degree and scope of the request. The following list 
describes each possible combination and its defined scope and degree: 


# If both a data item name-string and a non-zero format iden- 
tifier were specified, then the request is to terminate a single 
data-link for the specified data item and format specified. 

= If a data item name-string was specified and the format 
identifier contained a zero (0), then all data-links for the 
specified data item are to be terminated. 

# Ifazero-length string was specified for the data item and the 
format identifier was non-zero, then all data-links of the 
specified format for the client are to be terminated. 

= Ifazero-length string was specified for the data item and the 
format identifier contained a zero (0), then all data-links 
associated with the client are to be terminated. 


Client Server 


I no longer need updates. 


WinDdePostMsg ( ) WM_DDE UNADVISE Ok 


Thanks WinDdePostMsg ( ) 


Figure 4-4. Message Flow: DDE Unadvise 
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Listing 4-7 shows the DdeTerminateDataLink function. Called by 
a DDE client application, it will issue an Unadvise request to a server 
window specified in the hwndServer parameter. 


_ 
*K* 
ee FUNCT On: DdeTerminateLink 
K* 
we |Jsqge: Terminates a previously established data-link. 
K* 
ee / 
BOOL /* TResult: Success Indicator al 
APIENTRY DdeTerminateLink 
( 
HWND hwndServer /* desired server window handle ae 
HWND hwndClient /* requesting window handle ald 
PSZ pszItemName /* desired item name-string a 
, USHORT usFormat /* desired format a | 
) 
BOOL fResult = FALSE; 
PDDESTRUCT pDdeStruct = NULL; 
/ * 
** Creates a DDE shared memory object... 
at 
pDdeStruct = DdeMakeDdeStruct /* create a shared memory object * } 
( psziltemName /* null (0x00) terminated ASCII string ial 
» NULL /* pointer to data (not applicable) * f 
, OL /* size of data (in bytes) =e 
, usFormat /* registered DDE format identifier xf 
, 0 /* DDE status flags (not applicable) ald 
33 
/ * 
** If shared memory object successfully created... 
mf 
if (pDdeStruct) 
{ 
fResult = WinDdePostMsg /* post a DDE message to... ca 
( hwndServer ‘ie this requesting window handle, at 
, hwndClient fs from this responding window handle, */ 
, WM_DDE_UNADVISE ;* a “UnAdvise” message, ay 
, pDdeStruct /* as defined in this memory object, co 
DDEPM_RETRY fs and retry if receiving queue is full.*/ 


if 
} 
return (fResult); 


Listing 4-7. Client: Issue WM_DDE_UNADVISE (Terminate-link) 


xK* 
kK* 


*K* 


xK* 


FUNCTION: 


Usage: 


Remarks: 


1) 


2) 
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Listing 4-8 shows the DdeConvWmDdeUnAdvise function. This 


function is called by a server (WC_DdeConvy class) window when it 
receives a WM_DDE_UNADVISE message. 


DdeConvWmDdeUnAdvise 


Processes a “WM_DDE_UNADVISE” message dispatched to a 
“WC DdeConv” class window. 


The WM_DDE_UNADVISE message is posted by a client application to 
notify a server application that it should discontinue posting 
updates for a previously established data-link in the specified 
format for the specified item. 


It is possible that a client application has established more 
an one data-link with a server at a time. A client application 
does not need to terminate each data-link with a separate 
request. That is, updates can be discontinued for multiple 
items and formats with a single request. 


Any message posted in response should be to the window handle 
Specified in message parameter one (mpl). 


Determine the scope and degree of the request. The scope is 
determined by the presence of a item name-string and the degree 
1s determined by the value contained in the usFormat field in 
the DDESTRUCT structure. 


a) If the item name-string is zero-length, then the scope is 
all links associated with the conversation. Otherwise, the 
scope 1s limited to a specific item name. 


b) If the contents of the usFormat field of the DDESTRUCT 
Structure is zero (0), then the degree is all formats 
associated with the conversation. Otherwise, the degree is 
limited to a specific format. 


Given the above criteria, the following combinations are 
possible: 


a) If item name-string 1S a non zero-length string and a non 


Listing 4-8. Server: Process WM_DDE_UNADVISE (Terminate-link) 
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2) 


MRESULT 
EXPENTRY 


HWND 


MPARAM 
MPARAM 


BOOL 


b) 


c) 


d) 


Det 
est 
mes 


zero format identifier was specified, then the request is to 
discontinue updates for a specific item and format. 


if item name-string is a non zero-length string and zero was 
specified for the format identifier, then the request is to 
discontinue updates for all formats corresponding to the 
specified item. 


if item name-string is a zero-length string and a non zero 
format identifier was specie, then the request is to 
discontinue updates for a specific format in all items 
associated in a conversation. 


if item name-string is a zero-length string and zero was 
specified for the format identifier, then the request is to 
discontinue updates for all formats and all items associated 
in a conversation. 


ermine if the requesting client currently had a data-link 
ablished. If it did, respond with a positive WM_DDE_ACK 
Sage after completion of the unadvise operation. If the 


requesting client did not have an established data-link, respond 


wit 


Dde 
hwn 


mp1 
mp2 


fRe 


h a negative WM_DDE_ACK message. 


/* f1Reply: Reserved value, zero (0) 


ConvWmDdeUnAdvise 

d /* handle of window receiving message 
/* handle of window originating message 
/* pointer to DDESTRUCT structure 

sult = FALSE; 


Determine the scope of the request. Initially, the scope is defined to be 
all data items. 
of this conversation window. In a server configuration, the parent of a 
conversation window is a topic window. A topic window is always the 
parent of an item window. Therefore any and all items associated with a 
particular conversation will share a common parent with a conversation 


window. 


HWND 


hwn 


This is established by setting hwndScope to be the parent 


dScope = WinQueryWindow 
hwnd 
QW_PARENT 


fn 


Listing 4-8. (continued) 


/* 


xK* 


* I 


/* 


xK* 


my 
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Obtain “WC_DdeConv” window class info... 


PCONVINFO pConviInfo = (PCONVINFO) WinQueryWindowPtr 
( hwnd 
, OWL_USER 
| E- 

Obtain and set DDE transaction information... 


HWND hwndClient = HWNDFROMMP (mpl); 

PDDESTRUCT pDdeStruct = PVOIDFROMMP (mp2); 

PoZ psziltemName = (PSZ) DDES_PSZITEMNAME (pDdeStruct) ; 
USHORT usFormat = oDdeStruct->usFormat; 

USHORT fsStatus = 0; 

Insert message and associated information into listbox. 


Note: Typically, an application receiving a DDE message will free the 


associated shared memory object after processing this message (as 
Shown at the end of this function. However, we save the original 
Shared memory object for subsequent retrieval by the user. The 
Shared memory object is freed when the listbox is destroyed or 
cleared. 
SHORT SItemIndex = FrminsertListboxItem 
( hwndListBox 
, WM_DDE_UNADVISE 
ulMsglime 
, (ULONG) pDdeStruct 
ie 
The DDE protocol states that if no link existed for the specified 


jtem/format pair then the server must respond with a negative WM_DDE_ACK 
message. To determine the success or failure of this request, the global 
variable (fDataLinkExisted) is set to FALSE. Later, when the 
UM_UnAdviseItem message is broadcasted to each WC_DdeAdvise class window, 
the ’Advise’ window will set this flag to TRUE. Finally, the state of this 
flag will be checked and either a positive or negative WM_DDE_ACK message 
will be posted in response. 


fDataLinkExisted = FALSE; 


If the Item name-string iS a non zero-length string, then this request is for 
a specific item. 


if (strlen (pszItemName) ) 


Listing 4-8. (continued) 


78 


/* 
kK* 
xK* 


a | 


/* 
K* 
K* 


*y 


/* 
*xK* 
k* 


ay 


/* 
K* 
*xK* 
kK* 
k* 
k* 


ia 


/* 
*K* 
K* 


i 


/* 
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Set default query parameters: String comparisons are not case-sensitive, 
and are in the same codepage as the server. 


BOOL fCaseSensitive = FALSE; 
USHORT usCodepage = ConvContext.usCodepage; 


If a conversation context is associated with this conversation, 
determine context specific information. 


if (pConvinfo->pConvContext) 


Determine if string comparisons are case-sensitive. By default, all 
strings comparisons are not case-sensitive. 


if (pConvInfo->pConvContext->fsContext & DDECTXT_CASESENSITIVE) 
TCasesensitive = TRUE; 


Determine the codepage the requesting application is using. 

This is used to translate strings before comparisons are made. If 
the requesting application is using a different codepage than this 
application, then strings are first translated to the codepage in use 
by this application. 


usCodepage = pConvinfo->pConvContext->usCodepage; 


See if an item window exists whose text matches the item name-string 
contained in the request. 


hwndScope = DdeQuerylItemWindow 
( WinQueryWindow (hwnd, QW_PARENT ) 
, pszitemName 
, usCodepage 
, TCasesensitive 
,» BMSG_DESCENDANTS 
M; 


*x At this point the scope of the request has been determined. Now, the 
*k degree to which data-links are terminated is dependant on the value 
** specified in the usFormat field of the DDESTRUCT structure. 


Listing 4-8. (continued) 


oy 


/* 


x* 


*% 


/* 


*x* 


~~ 


/* 


*xK* 


a 
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if (hwndScope) 
{ 
fResult = WinBroadcastMsg /* broadcast a message to, 
( hwndScope /* the children of this parent window 
, UM_UnAdviseltem /* message identifier 


, MPFROMHWND (hwnd) /* message parameter one (mpl) 

, MPFROMSHORT (usFormat)/* message parameter two (mp2) 

, BMSG_SEND /* send the message to all children 
| BMSG_DESCENDANTS i* and their descendants. 


If ’unadvise’ transaction successfully processed... 


if (fDataLinkExisted) 
{ 

fsStatus = DDE_FACK; 
} 


Create a DDE shared memory object... 
pDdeStruct = DdeMakeDdeStruct 
( pszItemName /* jtem name-string 
» NULL /* pointer to data (not applicable 
, OL /* size of data (not applicable) 
, usFormat /* Registered DDE format identifier 
, fsStatus /* DDE status flags 
i 
If shared memory object successfully created... 
fResult = WinDdePostMsg /* post a DDE message to... 
( hwndClient eg this requesting window handle, 
, hwnd {* from the “Conv” window handle, 
, WM_DDE_ACK ih an “Acknowledgement” message, 
, pDdeStruct {* as defined in this memory object, 
, DDEPM_RETRY ;* and retry if receiving queue is full. 
Me 


The receiver of a DDE message is responsible for the memory object 
associated with a DDE message. The receiver must either reuse or free 
the memory object. The example programs retain the original memory 
object for subsequent retrieval. The following statement would normally 
be executed at this point and is shown here for completeness. 


DosFreeMem (PVOIDFROMMP (mp2)); 


Listing 4-8. (continued) 
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soe 
return (MRFROMSHORT (0)); 
/ * aa Se eS SS SS SS SS SS — 
DdeConvWmDdeUnAdvise 
This function is called when a (server) conversation window receives a 
WM DDE_UNADVISE message. 
The WM_DDE_UNADVISE message is posted by a client application to notify 
a server application that it should discontinue posting updates for a 
previously established data-link in the specified format for the specified 
item. 
SS SS ee a eee / 
MRESULT /* Reserved value, zero (0) sat | 
EXPENTRY DdeConvWmDdeUnAdvise 
( 
HWND hwnd 
, MPARAM mp1 
, MPARAM mp2 
) 
| 
BOOL FResult = FALSE: 
HWND hwndScope = WinQueryWindow 
( hwnd 
, QW_PARENT 
iy 
PCONVINFO pConvInfo = (PCONVINFO) WinQueryWindowPtr 
( hwnd 
, QWL_USER 
HWND hwndClient = HWNDFROMMP (mp1); 
PDDESTRUCT pDdeStruct = PVOIDFROMMP (mp2); 
PSZ pszItemName = (PSZ) DDES_PSZITEMNAME (pDdeStruct) ; 
SHORT SltemIndex = FrmInsertListboxItem 


( hwndListBox 

, WM_DDE_UNADVISE 

ulMsgTime 

, (ULONG) pDdeStruct 
ys 

** Determine the scope of the request. Initially, the scope is defined to be 

*x all data items. This is established by setting hwndScope to be the parent 

** of this conversation window. In a server configuration, the parent of a 

** conversation window is a topic window. A topic window is always the 

** parent of an item window. Therefore any and all items associated with a 

** particular conversation will share a common parent with a conversation 

*xk window. If the Item name-string is a non zero-length string, then this 


Listing 4-8. (continued) 


x 
a 
if 


/* 


xK* 
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request is for a specific item. 
(strlen (pszItemName) ) 
/* 


** Set default query parameters: String comparisons are not case-sensitive, 
** and are in the same codepage as the server. 


at 

BOOL fCaseSensitive = FALSE; 

USHORT usCodepage = ConvContext.usCodepage; 
/* 


** If a conversation context is associated with this conversation, 
** determine context specific information. 


if (pConvinfo->pConvContext) 


** Determine if string comparisons are case-sensitive. By default, 
** all strings comparisons are not case-sensitive. 


if (pConvinfo->pConvContext->fsContext & DDECTXT_CASESENSITIVE) 


fCaseSensitive = TRUE; 


** Determine the codepage the requesting application is using. 

** This is used to translate strings before comparisons are made. If 

** the requesting application is using a different codepage than this 

** application, then strings are first translated to the codepage in use 
** Dy This application. 

=y 

usCodepage = pConvInfo->pConvContext->usCodepage; 


** See if an item window exists whose text matches the item name-string 
** contained in the request. 

a 

hwndScope = DdeQueryItemWindow 

WinQueryWindow (hwnd, QW_PARENT) 

, psziltemName 

, usCodepage 

, tCaseSensitive 

» BMSG_DESCENDANTS 


“NN 


At this point the scope of the request has been determined. Now, the 


Listing 4-8. (continued) 
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degree to which data-links are terminated is dependant on the value 
specified in the usFormat field of the DDESTRUCT structure. 


(hwndScope) 
fResult = DdeBroadcastMsg 


( hwndScope 

, UM_UnAdviseltem 

, MPFROMHWND (hwnd) 

, MPFROMSHORT (pDdeStruct- 
, BMSG_SEND 

| BMSG_DESCENDANTS 

i. 


/* broadcast a message to, 


/* the children of this parent window */ 


/* this message, = 
/* message parameter one (mpl) * 
>usFormat) /* parameter two (mp2) “if 
/* send the message to all children * 
/* and their descendants. a 


Create a shared memory object to post acknowledgement to requesting 


pDdeStruct) 

pointer to data (not applicable) ad | 

size of data in bytes (not applicable) */ 

registered DDE format identifier a | 

success indicator... *Y 
if TRUE, post positive WM_DDE_ACK... */ 
else, post negative WM_DDE_ACK. * | 

window handle of requesting application*/ 


window handle of responding application*/ 
message identifier wf 
pointer to DDESTRUCT memory object a 
retry if destination queue was full wf 


The receiver of a DDE message is responsible for the memory object 
associated with a DDE message. The receiver must either reuse or free 
the memory object. The example programs retain the original memory 


The following statement would normally 


be executed at this point and is shown here for completeness. 


** window handle. 

af 

pDdeStruct = DdeMakeDdeStruct 
( (PSZ) DDES_PSZITEMNAME ¢ 
» NULL i> 
» BL pe 
, DUGEStPUCE->UsForhat ¢* 
, (fResult) f* 
? DDE_FACK ye 
amt f* 
3 

fResult = WinDdePostMsg 
( hwndClient [* 
, hwnd j* 
, WM_DDE_ACK /* 
, pDdeStruct fs 
, DDEPM_RETRY j* 
Ds 

/* 

K* 

*Kx* 

kx 

** object for subsequent retrieval. 

kK* 

Kx 

are DosFreeMem (PVOIDFROMMP (mp2)); 

= 

return MRFROMSHORT (0); /* 


reserved value, must be zero (0) * / 


Listing 4-8. (continued) 


Guidelines 


POKE 
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A client application must: 


a Allocate a shared memory object large enough to contain a 
DDESTRUCT structure. 

= Specify the desired data item and/or format identifier indi- 
cating which data-link to terminate. 

= Process the WM_DDE_ACK message posted in response to 
this request. The client application must determine if the 
Advise request was accepted. How the client application 
handles a positive or negative response is application-spe- 
cific. 


A server application must: 


= Respond to the window handle specified in message parame- 
ter one (mp1). 

= Determine if the client currently has a data-link established. 
If it does, it responds with a positive WM_DDE_ACK mes- 
sage after completion of the operation. If no link exists, the 
server responds with a negative WM_DDE_ACK message. 

= Determine the scope of the Unaduvise request; that is, is it a 
request for a specific data-link, or a wildcard request? 


Note: A server should ensure that no additional (WM_DDE_DATA) 
updates are posted between the time aWM_DDE_UNADVISE message 
is received and the time a positive WM_DDE_ACK message is returned 
in response. Although it is not illegal to post WM_DDE_DATA messages 
during this time period, it is considered a polite gesture on behalf of the 
server to honor the request immediately. 


= Free or reuse the shared memory object containing the 
DDESTRUCT structure. 


To request a server application to accept an unsolicited data item. If the 
server can accept the data item in the format specified, it updates the 
data item and responds by posting a positive WM_DDE_ACK message; 
otherwise, if the server cannot accept, it responds with a negative 
WM_DDE_ACK message. Figure 4-5 illustrates a simplified and suc- 
cessful Poke transaction. 
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Client Server 


Update this data item. 


WinDdePostMsg ( ) WM_DDE_POKE Ok, got it. 


WinDdePostMsg ( ) 


Figure 4-5. Message Flow: DDE Poke 


The function entered in Listing 4-9 can be issued, by a client applica- 
tion to “Poke” data, to a server application. 


Guidelines 


A client application must: 


Allocate a shared memory object large enough to contain a 
DDESTRUCT structure. 

Specify the desired data item and/or format identifier indi- 
cating which data item to update and what the format is. 
Process the WM_DDE_ACK message posted in response to 
this request. The client application must determine if the 
Advise request was accepted. How the client application 
handles a positive or negative response is application-spe- 
cific. 


A server application must: 


Respond to the window handle specified in message parame- 
ter one (mp1). 

Determine if it can update the data item and respond with a 
positive WM_DDE_ACK message after completion of the 
operation. Or, respond with a negative WM_DDE_ACK mes- 
sage if it cannot accept the data item. 

Free or reuse the shared memory object containing the DDE- 
STRUCT structure. A server can reuse the memory object 
when responding with a positive or negative WM_DDE_ACK 
message, rather than freeing one and creating another. 


/* 


K* 


i 
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Usage: 


BOOL 
APITENTRY 


HWND 
HWND 
Pod 
USHORT 
PVOID 
ULONG 


BOOL 
PDDESTRUCT 


Creates a DDE 


pDdeStruct 


DdePokeData 


Poke data to DDE ‘Client’ window. 


DdePokeData 


hwndServer 
hwndClient 
pszItemName 
usFormat 
pvData 
cbData 


fResult = FALSE; 


pDdeStruct NULL; 


= DdeMakeDdeStruct 
( pszItemName 

,» PyData 

, cbData 

, usFormat 

« 

1e- 


/* 


/* 
/* 
/* 
/* 
/* 
/* 


fResult: Success indicator 


desired server window handle 
requesting window handle 
desired item name-string 
desired format 

pointer to data 

Size of data (in bytes) 


Shared memory object... 


create a shared memory object 

null (0x00) terminated ASCII string 
pointer to data 

Size of data (in bytes) 

registered DDE format identifier 
DDE status flags (not applicable) 


If shared memory object successfully created... 


if (pDdeStruct) 


{ 
fResult 


= WinDdePostMsg 
( hwndServer 

, NhwndClient 

, WM_DDE_POKE 

, pDdeStruct 

, DDEPM_RETRY 
e. 


return (fResult); 


/* 


post a DDE message to... 
this requesting window handle, 
from this responding window handle, 
a “Poke” message, 
as defined in this memory object, 
and retry if receiving queue is full. 


Listing 4-9. Client: Issue WM_DDE_POKE 
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EXECUTE 


A client can request that a command or group of commands be executed 
by the server on its behalf. If the server is able, it attempts to execute 
the string of command(s). If the server is successful, it posts a positive 
WM_DDE_ACK message in response. If the executing fails, or if the 
server is unable to execute the commands, a negative WM_DDE_ACK 
message is posted in response. Figure 4-6 illustrates a simplified and 
successful Execute transaction. The function listed in Listing 4-10 can 
be issued by a client application to submit a list of commands to be 
executed by a server application. 


Guidelines 


=» The command string must be some agreed-upon protocol. 

=» Aserver should provide a list of supported (command string) 
protocols. A list of supported protocols should be made avail- 
able by a server application through the SZDDE SYS_- 
ITEM _ PROTOCOLS item of the System topic. 

s Ifthe server successfully executes the command, it posts a 
positive WM_DDE_ACK message to the client. If execution of 
the command is unsuccessful, a negative WM_DDE_ACK 
message is posted to the client. In both cases, the server in- 
cludes the original command received from the client in the 
acknowledgement message. Since the Execute transaction is 
not item-name-specific, this is the only method in which a cli- 
ent can determine the command that succeeded or failed. 


Client Server 


Update this data item. 


WinDdePostMsg ( ) WM_DDE_POKE Ok, got it. 


WinDdePostMsg () 


Figure 4-6. Message Flow: DDE Execute 
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iat | 


Function: DdeExecuteCommands 
Usage: Execute a string of commands contained in a CF_TEXIT buffer. 
BOOL /* fResult: Success indicator 


*xK* 


at 


/* 


K* 


a | 


APIENTRY DdeExecuteCommands 


HWND hwndServer Ve 
HWND hwndClient {x 
USHORT usFormat {* 
PVOID pvData ie 
ULONG cbData Le 
BOOL fResult = PALSEs 


PDODESTRUCT pDdeStruct 


Create a DDE shared memory object... 


NULL; 


pDdeStruct = DdeMakeDdeStruct a 


( NULL pe 
, pvData i 
, coData {* 
, DDEFMT_TEXT :* 
ae © {* 


}s 


desired server window handle 
requesting window handle 
desired format 

pointer to data 

Size of data (in bytes) 


create a shared memory object 
item name-string (not applicable) 
pointer to data 

Size of data (in bytes) 

text format 

DDE status flags (not applicable) 


If shared memory object successfully created... 


if (pDdeStruct) 


fResult = WinDdePostMsg /* 


( hwndServer /* 
, hwndClient i 
, WM_DDE_EXECUTE [* 
, pDdeStruct ys 
, DDEPM_RETRY js 


iE 
} 
return (fResult); 


post a DDE message to... 
this requesting window handle, 


from this responding window handle, 


an “Execute” message, 


as defined in this memory object, 
and retry if receiving queue is full. 


Listing 4-10. Client: Issue WM DDE EXECUTE 


my 


a 
sy 
a 
my 
a 
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Command String Syntax 


Conventions: 


= The left bracket ( [ ) denotes a single syntax element. 

a Optional syntax elements are enclosed in a pair of curly- 
brackets ( {} ). 

# An ellipse (...) denotes that multiple occurrences of the 
element are possible. 


Command string : = [opcodestring] { lopcodestring] } ... 


= Acommand string is a NULL (0x00) terminated string. If the 
data item contains more than one command string, the en- 
tire data item is NULL (0x00) terminated. In other words 
the data item is double NULL terminated. 

# Acommand string contains one or more opcodestrings. 


An opcodestring, one or more optional parameters, is defined as 
follows: 


opcodestring : = opcode { ( parameter { , parameter} ...) } 


=» An opcode is any application defined single-token. It may not 
include spaces, commas, parentheses, or quotation marks. 

# A parameter is any application-defined value. Multiple pa- 
rameters are separated by commas, and the entire parame- 
ter list is enclosed in parentheses. The parameter may not 
include commas or parentheses, except inside a quoted 
string. If a bracket or parentheses character is required in a 
quoted string, it must be doubled: ’((’. 


Example Command Strings 


[connect][download(query,results.txt) |[disconnect] 
[query(“sales per employee for each district”)] 
[open(“sample.xlm”)|[run(“r1c1")] 


TERMINATE 


An application terminates a DDE conversation by issuing a 
WM_DDE_TERMINATE message. The Terminate transaction is the only 
exception to the one-way rule regarding message flow in DDE. Aclient or 
a server application can terminate a DDE conversation at any time. Simi- 


Guidelines 
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Client Server 


Good bye. 


V 


WinDdePostMsg() |WM_DDE_TERMINAT Good bye. 


_DDE_TERMINATE| — WinDdePostMsg () 


Figure 4-7. Message Flow: DDE Terminate 


larly, a DDE application should be able to receive a WM_DDE_TERMI- 
NATE message at any time. Figure 4-7 illustrates a terminate sequence. 

The WM_DDE_TERMINATE message is an agreement (or promise) 
that the originator of the terminate request will post no further DDE 
messages. The recipient of the WM_DDE_TERMINATE message is free 
to destroy any resources that might have been created for the conversa- . 
tion; for example, the recipient can destroy windows that may have been 
created. 

Caution: It is possible that one or more messages from this partner 
were posted before it received the terminate request. Since the originat- 
ing application has just promised to post no further messages, it cannot 
issue a response to these unprocessed requests. It is legal to process 
these requests; however, no response should be given. 

Listing 4-11 shows the DdeConvWmDdeTerminate function. This 
function is called by a WC_DdeConv class window when it receives a 
WM_DDE_TERMINATE message. 


a» AWM_DDE_ TERMINATE message can be issued by either 
the client or the server application at any time. 

= Both applications must be able to _ process’ the 
WM_DDE_TERMINATE message at any time; that is, it is 
not permissible to respond with a negative, busy, or positive 
WM_DDE_ACK message. 

# Before an application terminates, it must terminate any and 
all active DDE conversations. Failure to comply will prohibit 
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Function: 


Usage: 


Remarks: 


Guidelines: 


DdeConvWmDdelerminate 


Processes a “WM_DDE_TERMINATE” message dispatched to a 
“WC_DdeConv” class window. 


A “WM_DDE_TERMINATE” message is an agreement (a promise) that 
the originator will post no further DDE messages. The receiver 
is free to destroy any resources that have been created for the 
conversation link. For example, windows and structures. 


The receiving application is expected to respond to this message 
by promptly posting a “WM_DDE_TERMINATE” message in response. 

It is not legal to post a positive, negative, or busy 
“WM_DDE_ACK” message in response to a ‘Terminate’ request. 


1) Any message posted in response should be to the window handle 
Specified in message parameter one (mpl). 

#) A “WM _DDE_TERMINATE” message can be issued by either the client 
or the server application at any time. 

3) An applications must be able to process the “WM _DDE_TERMINATE” 
message at any time. That is, it 1S not permissible to respond 
with a negative, busy or positive “WM_DDE_ACK” message. 

4) Before an application terminates, it must terminate any and all 
active data and conversation links. Failure to terminate these 
links will prohibit applications engaged in conversation from 
discarding resources associated with such links. 

oe: The originator agrees not to issue any further transactions 
associated with this conversation link. 

6 ) Once issued an application should ignore any subsequent messages 
from this conversation partner. Additional messages are 
possible if messages where posted prior to the receipt of a 
“WM DDE_TERMINATE” message. 

MRESULT /* flReply: Reserved value, zero (0) we 
EXPENTRY DdeConvWmDdelerminate 

HWND hwnd /* handle of window this message ia | 
MPARAM mp1 /* window handle originating message iat J 


Listing 4-11. Client/Server: Process WM_DDE_INITIATE 


/* 


K* 


a 


BOOL 


fResult = 
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FALSE: 


Obtain “WC _DdeConv” window class info... 


PCONVINFO 


pConvinfo 


a, 


}; 


(PCONVINFO) WinQueryWindowPtr 
hwnd 
QWL_USER 


Insert message and associated information into listbox. 


Note: Typically, an application receiving a DDE message will free the 
associated shared memory object after processing this message (as 
Shown at the end of this function. However, we save the original 
shared memory object for subsequent retrieval by the user. The 
Shared memory object is freed when the listbox is destroyed or 
cleared. 


SHORT 


Promptly 


fResult 


sItemIndex = 


FrminsertListboxItem 
hwndListBox 


, WM_DDE_TERMINATE 


ulMsglime 


, UL 


iF 


respond by *posting’ a “WM_DDE_TERMINATE” message... 


WinDdePostMsg 
HWNDFROMMP (mpl 
hwnd 

WM DDE_TERMINAT 
NULL 
DDEPM_RETRY 


j= post & DUE message To... 
) /* this requesting window handle, 
fe from the “Conv” window handle, 
E [* an “Terminate” message, 


da as defined in this memory object, 
pe and retry if receiving queue is full. 


Notify all child (WC_DdeItem and WC_DdeAdvise class) windows to ‘terminate’ 
Lieir date-linkSs.. 


Note: The ‘parent’ of a “WC_DdeConv” class window, is also the ‘parent’ 
of ‘Topics’ and ‘Items’ associated with the conversation link. This 
relationship is guaranteed by the design of the example programs. 


fResult 


( 


> 


WinBroadCastMsg 
WinQueryWindow 

UM_UnAdviseltem 
MPFROMHWND (hwn 


(hwnd, QW_PARENT ) 
d) 


Listing 4-11. (continued) 
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/* 


kK* 


ae 5 


/* 


*K* 


af | 
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, MPFROMSHORT (0) 


ie 


Notify our ‘owner’ 


BMSG_SEND 
BMSG_DESCENDANTS 


the this conversation link terminated... 


fResult = (BOOL) WinSendMsg 
( hwndClient 
, UM_Terminate 
, MPFROMP (pConvInfo->szAppName) 
, MPFROMP (pConvinfo->szTopic) 


iE 


Finally, destroy this conversation link window and all its children... 


fResult = WinDestroyWindow 


( hwnd 
13 


return (MRFROMSHORT 


/* handle of window to destroy a 


0G BE 


Listing 4-11. (continued) 


applications engaged in DDE conversations from discarding 
its resources. 

The receiving application is expected to post a 
WM_DDE_TERMINATE message in response. It not legal to 
post a negative WM_DDE_ACK message. 

By issuing a WM_DDE_TERMINATE message, the sender 
agrees not to issue any further transactions associated with 
this conversation link. This allows the recipient to discard 
any resources (such as a window) that were allocated for the 
conversation. 

Once an application has issued a WM_DDE_TERMINATE 
message, it should ignore any subsequent messages from 
this conversation partner. Additional messages are possible 
if messages were posted prior to the receipt of a 
WM_DDE_TERMINATE message. 


5 


The System Topic 


The System topic provides general and specific information about a 
server’s capabilities and status. Although not required, DDE server 
applications are encouraged to support this topic, support that serves a 
dual purpose: 


1. Client applications can obtain current (and often changing) 
information regarding the server. 
2. Asimpler form of generalized conversation is possible. 


As mentioned in Chapter 2, “The DDE Initiation Process,” a client 
application can use a technique known as wild-cards (the first form of 
generalized conversation) to obtain a list of active servers. This tech- 
nique is somewhat inefficient in that every active server responds once 
for each supported topic. The client application must then discard (and 
Terminate) duplicate and unwanted conversation links. 

By supporting the System topic, client applications can limit the 
number of responses to one per active server. This is accomplished by 
issuing an /nitiate request, specifying NULL as the Application name- 
string, and specifying SZDDESYS_TOPIC as the topic name-string, as 
shown here: 
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BOOL 
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fResult = WinDdelInitiate 


( 


hwnd 


» NULL 
, SZDD 


, NULL 
ee 


Client /* handle of originating client application (window) * 
/* Application name-string a i 
Est s_fOPIC /* Topic name-string “ys 
/* address of Conversation Context structure a | 


When an active server receives the corresponding WM_DDE_INITI- 
ATE message, only a single response is required. By specifying a topic 
name, the number of responses generated from a generalized initiate 
request is greatly reduced. However, since support of topic is not re- 
quired or enforced, it cannot be assumed that all DDE server applica- 
tions support it (especially older Windows applications). The System 
topic name-string is defined as “System” and is declared by the 
SZDDESYS_TOPIC definition in the PMWIN.H header file. 

Aclient DDE application must first engage in a DDE conversation with 
a server on this topic before information regarding it can be requested. 
Once engaged, a client can obtain a list of supported items by issuing a 
DDE Request transaction on the SZDDESYS_ITEM_SYSITEMS item. If 
supported (as recommended), the requesting application will receive a 
TAB (0x09) delimited list of NULL (0x00) terminated text strings, one 
string for each item supported. 

A set of suggested data items to be supported with the System topic 
also exists. Each data item and its corresponding declaration are listed 
in Table 5-1. Refer to the PMWIN.H header file for a complete and 
updated list of System items. 

The following items should be supported under the System topic: 


System data items must be rendered in the Text format (refer 
to Chapter 3 for a description of this format). It is legal for a 
client application to request these items in another format; 


TABLE 5-1. System Items 


SZDDESYS_ITEM_TOPICS “Topics” 
SZDDESYS_ITEM SYSITEMS “SysItems” 
SZDDESYS_ITEM_ RTNMSG “ReturnMessage” 
SZDDESYS_ITEM STATUS “Status” 
SZDDESYS_ITEM FORMATS “Formats” 
SZDDESYS_ITEM ITEMFORMATS “ItemFormats” 
SZDDESYS_ITEM_ SECURITY “Security” 
SZDDESYS_ITEM_ PROTOCOLS “Protocols” 
SZDDESYS_ITEM RESTART “Restart” 


SZDDESYS ITEM HELP “Help” 
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for example, SZFMT_CPTEXT. However, it is not required 
and therefore not an error if the server application does not 
or cannot support any other format other than Text. 

Individual elements of lists must be delimited by the TAB 
character (0x09) and terminated by a single NULL (0x00) 
character. For example, if a server application supported the 
CF_TEXT, CF_BITMAP and CF_METAFILE formats, the 
following illustrates how the SZDDESYS_ITEM_FORMATS 
should be rendered: 


Text(0x09)Bitmap(0x09)Metafile(0x00) 
The following items should be supported under the System topic: 


SZDDESYS_ITEM_ TOPICS A list of topic strings currently 
supported by the application. This list can vary from moment 
to moment. 

SZDDESYS_ITEM_SYSITEMS A list of items supported by 
this application under the System topic. 

SZDDESYS_ITEM_RTNMSG Extended information regard- 
ing the most recently-issued WM_DDE_ACK message. This 
is useful when more than 8 bits of application-specific return 
code are required. These 8 bits refer to the upper 8 bits of the 
fsStatus field of the DDESTRUCT structure when the 
DDE_FAPPSTATUS indicator is present. 

SZDDESYS_ITEM STATUS An indication of the current 
status of this application. This string must be equal to 
“Ready” if the server is active and can respond to requests, 
otherwise this string must be equal to “Busy” if it cannot. Any 
other string is undefined and is application-specific. 

SZDDESYS_ITEM_ FORMATS A list of formats this applica- 
tion is currently capable of rendering. Typically, applications 
leave off the “CF_” or the “DDEFMT_” prefix; for example, 
CF_TEXT would be defined as “Text”. In addition, a server 
should render this list in order of preference. 

SZDDESYS_ ITEM ITEMFORMATS A list of formats in 
which system items can be rendered. This item is becoming 
somewhat obsolete since most applications are only required 
to support CF_TEXT clipboard format when rendering sys- 
tem items. (See “SZDDESYS_ITEM_ FORMATS” for require- 
ments/restrictions regard the rendering of this item.) 

SZDDESYS_ITEM_SECURITY If supported, the DDE server 
application is security-sensitive. Any client can initiate a 
conversation with a security-sensitive server; however, the 
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server responds only to the Security item of the System topic. 
Typically, this class of server requires a password from a 
client before any further data exchange can take place. 

SZDDESYS_ITEM PROTOCOLS A list of command strings 
the server currently supports. It is typically a list of particu- 
lar commands, general syntax, or both. 

SZDDESYS_ITEM_ RESTART A string that a client can pass 
to DosExecPgm to invoke a server that is not running; for 
example, “DDEServer.exe”. 

SZDDESYS_ITEM HELP A text description of the services 
provide by the server. It is possible that this text changes due 
to the changing capabilities of the server application. 


6 


Differences Between PM and Windows DDE 


This section describes the differences in the implementation of the DDE 
protocol on the Windows environment and the OS/2 operating system. 
By identifying these differences, a subset of the protocol is defined. 
Applications adhering to this subset will be compatible with most DDE 
applications regardless of whether the application is running in a PM 
or a WIN-OS2 session. 

When the DDE protocol was migrated from the Windows implemen- 
tation, certain changes where required. For the most part, these 
changes where required because of the multitasking, protected memory 
environment of the OS/2 operating system. The primary change was to 
allow for the passing of a memory object to another application, which 
involved crossing process boundaries. 

In the Windows environment a handle to the memory object is suffi- 
cient, whereas, in the OS/2 operating system, a memory object must be 
allocated from shared memory and access granted to the receiving 
application. Rather than requiring an application to handle these tasks, 
a set of APIs is defined in PM that handle giving the memory to the 
receiving process and, in the case of Initiation, allocating the shared 
memory object. This set of PM APIs is listed as follows: 


e WinDdelnitiate 


=» WinDdeRespond 
2» WinDdePostMsg 
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Among the major differences between the two implementations are 
the parameters passed in a DDE message. Like its Windows counter- 
part, the first parameter of a DDE message is always the window 
handle of the originating application. Unlike its Windows counterpart, 
the second parameter is always a pointer to a consistent (DDE- 
STRUCT or a DDEINIT) data structure. (In the Windows environ- 
ment, the contents of the second parameter depend on the message. ) 


ATOM MANAGEMENT 


Both PM and Windows use the global atom manager for registering 
private DDE format identifiers. Windows uses atoms for passing of 
application, topic, and item name-strings; in PM, these strings are 
passed in the structures accompanying the message. 


MEMORY MANAGEMENT 


STATUS FLAGS 


Memory management is considerably different in the PM and Windows 
implementations. In PM, memory objects passed in DDE transactions 
are allocated from shared memory. A pointer to this shared memory 
object is passed in message parameter two (mp2) of a DDE message. In 
Windows, a handle to the associated memory object is passed. Once 
received, the Windows application must issue a GlobalLock API on the 
specified handle in order to obtain an address of the memory object. 


PM flags are globally defined and do not depend on a specific message 
type. Table 6-1 lists each status flag and its counterpart: 


1. PM memory rules do not allow the originator to control 
memory management. 

2. The DDE_FACKREQ status flag relieves the fAck status flag 
from the double-duty it serves in the Windows environment. 

3. Not defined in the Windows implementation of the protocol 

4. Not defined in the Windows implementation of the protocol. 


MESSAGES and STRUCTURES 


Information transferred through DDE messages utilize a single struc- 
ture for data transfer. This differs from Windows, in which the format 
of the information depends on the message. 
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TABLE 6-1. DDE Status Flag Comparison 


Windows Presentation Manager 
fRelease (1) 
fAck (to request acknowledgement) DDE_FACKREQ (2) 
fAck (as an acknowledgement) DDE_FACK 
fBusy DDE_FBUSY 
fDeferUpd DDE_FNODATA 
fResponse DDE_FRESPONSE 
fReserved DDE_FRESERVED 

(3) DDE_FAPPSTATUS 

(4) DDE_FNOTPROCESSED 


For the most part, wParam and /Param in a Windows message 
correspond to the mp1 and mp2 parameters of a PM message, respec- 
tively. Additional differences in DDE messages follow. 


WM_DDE_ACK 


In Windows, the WM_DDE_ACK message performs a double duty; that 
is, it is used to respond to a WM_DDE_INITIATE message in addition 
to the other DDE transaction messages. This differs from PM, where the 
WM_DDE_ACK message is used only to acknowledge DDE transaction 
messages, and the WM_DDE_INITIATEACK is used to respond to the 
WM_DDE_INITIATE message. 

A Windows application uses the DDEACK structure to provide de- 
tails about the acknowledgement, whereas a PM application supplies 
this information in a DDESTRUCT structure. The following is a defi- 
nition of the DDEACK structure as defined in the Windows DDE.H 
header file: 


typedef struct tagDDEACK /* ddeack ia 
WORD bAppReturnCode:8, 
reserved:6, 
fBusy:1, 
TACK 13 
} DDEACK; 


Additional Differences 


= In a Windows environment, the WM_DDE ACK message 
does not specify which format the acknowledgement is for. A 
Windows application must incorporate a scheme to associate 
WM_DDE_ACK responses to its original request, whereas a 
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PM application can utilize the format identifier to associate 
acknowledgements when multiple requests are outstanding. 

# In a Windows environment, the application status flags are 
contained in the low-order byte of the DDEACK structure. 
In a PM environment they are contained in the high-order 
byte of the fsStatus field. 


WM_DDE_ADVISE 


The WM_DDE_ADVISE message serves the same purpose in both en- 
vironments. 

In a Windows environment, the second (/Param) contains a 
DDEADVISE structure that specifies how the receiving application 
should post subsequent WM_DDE_DATA messages. In a PM environ- 
ment this same information is passed in a DDESTRUCT structure. 
The following is a definition of a DDEADVISE structure as defined 
in the Windows DDE.H header file: 


typedef struct tagDDEADVISE /* ddeadv Sf 
{ 
WORD reserved:14, 
fDeferUpd:1, 
fAckReq:1; 
Short cfFormat; 
} DDEACK; 


Additional Differences 


WM_DDE_DATA 


= In a PM environment, the responding application also sets 
the DDE_FNODATA status flag in the subsequent 
WM_DDE_DATA message if the data portion is zero-length. 


The WM_DDE_DATA message serves the same purpose in both environ- 
ments. 

A Windows application uses the DDEDATA structure to provide 
details about the data message, whereas a PM application supplies 
this information in a DDESTRUCT structure. The following is a defi- 
nition a DDEDATA structure as defined in the Windows DDE.H 
header file: 
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typedef struct tagDDEDATA /* ddedat al | 
WORD unused:12, 
fResponse:1, 
fRelease:l, 
reserved;l, 
FfAckReq:1; 
Short cfFormat; 
BYTE Valuell]; 
DDEDATA; 


Additional Differences 


uw fRelease has no meaning in a PM environment. PM does not 
allow the originator of a DDE message to control memory 
management. 


WM_DDE_EXECUTE 


The WM_DDE_EXECUTE message serves the same purpose in both 


environments. 


There is no structure associated with this message in a Windows 
environment. In both environments, the acknowledging application 
should include the original command strings in the associated 
WM_DDE_ACK message. In a Windows environment, this means speci- 
fying the same hCommands as in the request. In a PM environment, 
this means including the same data portion as in the request. 


WM_DDE_INITIATE 


The WM_DDE_INITIATE message serves the same purpose in both 


environments. 


In a Windows environment, this message is sent using the SendMsg 


API, as follows: 


ATOM atomAppName = GlobalAddAtom (“MyAppName”) ; 
ATOM atomTopic = GlobalAddAtom (“MyTopic”); 


BOOL fResult; 


fResult = SendMsg 
( HWND_ BROADCAST 
» WM_DDE_INITIATE 
» hwndMyClient 
, MAKELONG (atomAppName, atomTopic) 


) 


GlobalDeleteAtom (atomAppName) ; 
GlobalDeleteAtom (atomTopic); 
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In a PM environment, the WM_DDE_INITIATE is sent when an 
application issues the WinDdelnitiate API, as follows: 


BOOL fResult = WinDdelInitiate 
( “MyAppName” 
, MyTopic” 
,; Poors 


WM_DDE_INITIATEACK 


The WM_DDE_INITIATEACK message does not exist in a Windows 
environment. In a Windows environment, the WM_DDE_ACK message 
serves a dual purpose, of which responding to a WM_DDE_INITIATE 
message is one. 


WM_DDE_POKE 


The WM_DDE_POKE message serves the same purpose in both envi- 
ronments. 

In a Windows environment, the second (lParam) contains a DDE- 
POKE structure that specifies information about the data being sub- 
mitted. In a PM environment this same information is passed in a 
DDESTRUCT structure. The following is a definition of a DDEPOKE 
structure as defined in the Windows DDE.H header file: 


typedef struct tagDDEPOKE /* ddepok ce 
{ 


WORD unused:13, 
fRelease:l, 
fReserved:2, 

Short cfFormat; 

BYTE Valuell]; 

DDEDATA; 


Additional Differences 


as fRelease has no meaning in a PM environment. PM does not 
allow the originator of a DDE message to control memory 
management. 


WM_DDE_REQUEST, WM_DDE_TERMINATE, and WM_DDE_UNADVISE 


These messages serve the same purpose in both environments. In a 
Windows environment, these messages contain no associated data 
structures. 


CONVCONTEXT 


Appendix A 


DDE Structures 


This appendix describes each DDE structure. 


The CONVCONTEXT defines the context of a DDE conversation. By 
defining a conversation context, applications using different national 
languages can communicate and exchange data. The context of a con- 
versation context is specified during the DDE Initiation process when 
the WinDdelnitiate and WinDdeRespond APIs are issued. Both 
APIs take in the address of a memory buffer containing a CONVCON- 
TEXT structure as a parameter. 


typedef struct _CONVCONTEXT 

ULONG cb; 

ULONG fsContext; 

ULONG idCountry; 

ULONG usCodepage; 

ULONG usLangID; 

ULONG usSubLangID; 
CONVCONTEXT; 
typedef CONVCONTEXT *PCONVCONTEXT; 
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ch 


Size of CONVCONTEXT structure (in bytes). This field must be set to 
the total size of the CONVCONTEXT structure. For example: 


ConvCtx.cb = sizeof (CONVCONTEXT); 
fsContext 
Option flags. Currently, only one flag is defined: 
DDECTXT_CASESENSITIVE 


If this flag is present, string comparisons on application name, topic, 
item name, and command strings are case-sensitive. 


ConvCtx.fsContext = 0; 

idCountry 

Country code in use by requesting application. 
ConvCtx.idCountry = CtryInfo.country; 

usCodepage 

Codepage in use by requesting application. 
ConvContext.usCodepage = WinQueryCp (hmq); 


usLanglD 


Language Identification. Zero is valid and indicates no language infor- 
mation. 


ConvCtx.usLangID = 0; 


usSubLangID 


Sub-language Identification. Zero is valid and indicates no sub-lan- 
guage information. 


ConvCtx.usSubLangID = 0; 


APPENDIX A / DDE STRUCTURES 105 


Given the following code fragment, statements specified for each item 
may be executed to initialize these items. These initializations are for 
example ONLY! Actual values for these items may vary and are appli- 
cation-specific. 


APIRET ApiRet; 
CONVCONTEXT ConvCtx; 
COUNTRY INFO Gtryinto: 


CUNTRYCODE CtryCode; 

CtryCode.country = OL; /* Query default system country code * f 

CtryCode.codepage = OL; /* Query current process codepage a 

ApiRet = DosQueryCtryInfo /* Query country-dependent information a 
( sizeof (CtryInfo) /* Size in bytes to hold returned info a | 
, &CtryCode /* Specifies criteria in which to query info sa 
, &CtrylInfo /* Memory buffer to receive queried info mf 
, &cbReturned /* Length, in bytes of actual returned info lt 
ys 

CPTEXT 


A CPTEXT structure is the first part of a variable-length memory 
object used to exchange text data in different codepages without having 
to establish a new conversation link. 


typedef struct _CPTEXT 

| 
USHORT idCountry; 
USHORT usCodepage; 
USHORT usLangID; 
USHORT usSubLangID; 
BYTE abText[1]; 

CPTEXTs 


idCountry 

Country code text is rendered in 
CPText.idCountry = CtryInfo.country; 

usCodepage 

Codepage text is rendered in 


CPText.usCodepage = WinQueryCp (hmaq); 
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usLanglD 
Language Identification. Zero is valid and indicates no language infor- 
mation. 
CPText.usLangID = 0; 
usSubLangID 
Sub-language Identification. Zero is valid and indicates no sub-lan- 
cuage information. 
CPText.usLangID = 0; 
abText 
Array of bytes containing text data. This data must be in 
DDEFMT TEXT format. 

Given the following code fragment, statements specified for each item 
may be executed to initialize these items. These initializations are for 
example ONLY! Actual values for these items may vary and are appli- 
cation-specific. 

APIRET ApiRet: 

GPT eat CPText; 

COUNTRY INFO Ctrylnfo; 

COUNTRYCODE CtryCode; 

CtryCode.country = OL; /* Query default system country code mf 

CtryCode.codepage = OL; /* Query current process codepage ey 

ApiRet = DosQueryCtryInfo /* Query country-dependent information ae J 
( sizeof (CtryInfo) /* Size in bytes to hold returned info mf 
, &CtryCode /* Specifies criteria in which to query info mp 
, &CtrylInfo /* Memory buffer to receive queried info my 
, &cbReturned /* Length, in bytes of actual returned info adj 
e 

DDEINIT 


A DDEINIT structure is the first part of a variable-length memory 
object used during the DDE initiation process. This memory object is 
created internally by the WinDdelnitiate and WinDdeRespond 
APIs. The total size of the memory object is dependent on the parame- 
ters passed in the API call. 
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typedef struct _DDEINIT 


ULONG cb; 

POL pszAppName; 

Poz pszlopic; 

ULONG offConvContext; 
DDEINIT; 


typedef DDEINIT *PDDEINIT; 


ch 


Length of DDEINIT structure. This must be set to the TOTAL length 
of the DDEINIT structure. This includes the size of the DDEINIT 
structure itself; the length of both the application name and topic 
name-strings, including the terminating NULL (0x00) character; and 
the size of the CONVCONTEXT structure (if any). Although the receiv- 
ing application does not have to calculate this field, it is helpful to know 
how it is calculated. The following code fragment illustrates this calcu- 
lation. 

USHORT cbAppName 


USHORT cbTopicName 
USHORT cbConvContext 


Strlen (pszAppName) + 1; 
strlen Cpszlooie) + 1; 
(pContext) ? (USHORT) 
pContext > cb: ©; 


cb = sizeof (DDEINIT) structure 
+ sizeof (CONVCONTEXT ) 
+ cbAppName 
+ Gblopic 
+ CoConvContet: 


Note: pContext refers to the pContext parameter of the WinDdelnitiate 
API. 


pszAppName 


Pointer to a NULL (0x00) terminated text string containing the name 
of the requested or responding server application. The text string can- 
not contain the reserved slashes or back-slashes characters. This may 
be a zero-length string when associated with a WM_DDE_INITIATE 
message. When associated with a WM_DDE_INITIATEACK message, 
this string should contain a non-zero-length string. However, it is not 
enforced. 


pszlopic 


Points to a NULL (0x00) terminated string containing the name of 
a topic. This may be a zero-length string when associated with a 
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WM_DDE_INITIATE message. When associated with a WM_DDE_IN- 
ITIATEACK message, this string should contain a non-zero-length 
string. However, it is not enforced. 


offConvContext 


Offset toa CONVCONTEXT structure. If no CONVCONTEXT struc- 
ture is present, this field will contain a value of zero. 

The following code fragment obtains a pointer to a CONVCONTEXT 
structure from a DDEINIT structure: 


PDDEINIT pDdelInit = (PDDEINIT) PVOIDFROMMP (mp2); 
PCONVCONTEXT pConvContext = null; 
if (pDdeInit->offConvContext ) 
| 
pConvContext = DDEI_PCONVCONTEXT (pDdelInit); 


Note: DDEI_LPCONVCONTEXT is a C-language macro. Further in- 
formation regarding this macro can be found in Appendix D. 


A DDESTRUCT structure is the first part of a variable-length memory 
object passed between applications during DDE transactions. This 
structure must be created from shared memory and must be large 
enough to contain the DDESTRUCT structure, an item name-string, 
and any data. A helper routine, DdeMakeDdeStruct, is listed in Ap- 
pendix F; it facilitates the proper creation of this structure. 


typedef struct _DDESTRUCT 


ULONG cbData; 

USHORT Tsstatus;: 

USHORT usFormat; 

USHORT offszItemName; 

USHORT offabData; 
DDESTRUCT; 


typedef DDESTRUCT *PDDESTRUCT ; 


chData 


Size of data (in bytes) contained in the data portion (that portion that 
begins at offabData) of this structure. cbData must be set to zero (0) if no 
data is present. The size of the structure or the length of the item name 
should not be included in this calculation; it is only the size of the data 
portion. 
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fsStatus 


Status flags (see “DDE Status Flags” in Appendix E for detailed infor- 
mation regarding each status flag). 


usFormat 


Identifies the format (and subsequently the layout) of the data con- 
tained in the data portion of this message (see “DDE Status Formats” 
in Chapter 3 for a complete description on the meaning of this field). 


offszitemName 


Offset to beginning of the item name-string. This is the offset from the 
beginning of the memory object to the start of a NULL (0x00) termi- 
nated ASCII text string. The item name-string identifies the item this 
message is referring to. The following code fragment correctly calculates 
this value and assumes that pDdeStruct points to a valid memory 
object: 


PDDESTRUCT pDdeStruct; 
pDdeStruct->offszItemName = sizeof (DDESTRUCT); 


Note: If anitem name is not required, a single NULL (0x00) character 
must be placed at this offset. For example, the WM_DDE_EXECUTE 
message does not require an item name. 

The following code fragment obtains a pointer to the item name- 
string: 


PDDESTRUCT pDdeStruct = (PDDESTRUCT) PVOIDFROMMP (mp2); 
PSZ pszItemName = (PSZ) null; 


if (pDdeStruct->offszitemName) 
pszItemName = DDES_PSZITEMNAME (pDdeStruct); 


Note: DDES_PSZITEMNAME is a C-language macro. Further infor- 
mation regarding this macro can be found in Appendix D. 


offabData 


Offset to beginning of data. This is the offset from the beginning of the 
memory object to the start of the data portion, if any. This field is only 
valid if cbData is greater than zero (0). Typically, this field is calculated 
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regardless of the presence of data. It is legal to set this field at zero (0) 
if no data is present. 

The following code fragment correctly calculates this value and as- 
sumes that pDdeStruct points to a valid memory object: 


PDDESTRUCT pDdeStruct; 
pDdeStruct->offabData = sizeof (DDESTRUCT) + (strlen (szItemName) + 1); 


Note: This field has a non-zero value if the DDE Message is originat- 
ing from a Windows application. If no data is present, cbData will 
contain a value of zero and offabData will contain a value calculated as 
shown above. 

The following code fragment obtains a pointer to the data portion: 


PDDESTRUCT pDdeStruct 
PBYTE pbData 


(PDDESTRUCT) PVOIDFROMMP (mp2); 
(PBYTE) nulls 


if (pDdeStruct->offabData) 
pbData = DDES_PABDATA (pDdeStruct); 


Note: DDES_PABDATA is a C-language macro. Further information 
regarding this macro can be found in Appendix D. 


Caution: For reasons of compatibility, this data should not contain 
embedded pointers or handles. Embedded pointers and handles require 
the receiving application to know of their existence and manipulate 
them appropriately. For example, if information exchange is between 
16-bit and 32-bit applications, the receiving application would have to 
do the necessary thunking. 

Moreover, if information is being exchanged between a Windows and 
PM application, a pointer or handle will have no meaning in another 
session! Also, the agents responsible for inter-vdm DDE communica- 
tions examine the data portion to convert standard DDE formats; they 
do not examine the data portion of private formats. 


A MFP structure is the first part of a variable-length memory object 
used to exchange metafile bits. This structure is used when additional 
information is required to properly render the metafile. 
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typedef struct _MFP 


POINTL SizeBounds; 

POINTL SizeMM; 

ULONG cbLength; 

USHORT mapMode; 

USHORT reserved; 

BYTE abDataLl]; 
} MFP; 


sizeBounds 


Metafile size in notional units. This contains the width and height of the 
bounding rectangle containing the metafile picture. The values con- 
tained in this field are in wnits corresponding to the mapMode. 


sizeMM 


Metafile size in high metric units. This contains the suggested width ~ 
and height of the rectangle in which the metafile picture is rendered. 


chLength 
Size of metafile bits in bytes. The metafile bits begin at the abData field. 


mapMode 


PM metafile map mode. This field identifies the Presentation-space 
page-units in effect when the metafile was created. This field can con- 
tain one of the following: 


PU_ARBI TRARY 
Puc Pel 

PU_LOMETRIC 
PU_HIMETRIC 
PU_LOENGLISH 
PU_HIENGLISH 
PU_TWIPS 


reserved 


Reserved value, must be zero (0). 


abData 


Beginning of metafile-bits that represent the metafile. 


Appendix B 


DDE Messages 


This appendix describes each DDE message. Table B-1 lists each DDE 
message and its identifier as defined in the PMWIN.H header file. 


Note: WM_DDE_FIRST and WM_DDE_LAST are not valid DDE 
messages. These definitions are used only to determine if a message 
value falls in the range of valid DDE messages. 


WM_DDE_ACK 


Purpose 


Indicates receipt and processing of WM_DDE_DATA, WM_DDE_AD- 
VISE, WM_DDE_UNADVISE, WM_DDE_EXECUTE, WM_ DDE_ 


TABLE B-1. DDE Message Identifiers 


#define WM_DDE_FIRST 0x00A0 
#define WM_DDE_INITIATE 0x00A0 
#define WM_DDE_REQUEST Ox00A1 
#define WM_DDE_ACK 0x00A2 
#define WM_DDE_DATA 0x00A3 
#define WM_DDE_ ADVISE 0x00A4 
#define WM_DDE_UNADVISE Ox00A5 
#define WM_DDE_POKE 0x00A6 
#define WM_DDE_EXECUTE 0x00A7 
#define WM_DDE_TERMINATE 0x00A8 
#define WM_DDE_INITIATEACK 0x00A9 
#define WM DDE LAST Ox00Af 
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POKE messages, and possibly a WM_DDE_REQUEST message. This 
message is always posted. 


mp] (HWND) 
Window handle of the responding application. 


mp2 (PDDESTRUCT) 


Points to a DDESTRUCT structure. (See “DDESTRUCT” in Appendix 
A for complete details regarding this structure.) 

Caution: Use of undefined fields is application-dependent and may 
cause unpredictable results. 


chData 


Size of the data portion (in bytes, starting at offabData) of this message. 
Typically, this field will be zero (0). However, if this message was posted 
in response to a WM_DDE_EXECUTE request, this field will have a 
non-zero value and the original command string will exist in the data 
portion. 


fsStatus 


The acknowledging application sets this field to indicate the processing 
status of the message received. The following constants are defined as 
bitmasks in the PMWIN.H header file. To determine if the value is set 
in the fsStatus field, a bitwise AND operation is performed on this field. 
For example, 


BOOL fAck = (fsStatus & DDE_FACK) ? TRUE : FALSE; 


DDE_FACK 


If set, this is a positive acknowledgment. If not set, this is a 
negative acknowledgment. 


DDE_FBUSY 


If set, acknowledging application was busy and did not process 
the request. This flag is only valid if DDE_FACK is not set. 


Return Value 


APPENDIX B / DDE MESSAGES 115 


DDE_NOTPROCESSED 


If set, the associated request is not supported by the acknow- 
ledging application and was ignored. For example, an appli- 
cation does not support the WM_DDE_EXECUTE or 
WM_DDE_POKE request. This flag should not be confused 
with a negative acknowledgement. Prior documentation 
stated that this flag should be set as an indicator of negative 
acknowledgement; although not illegal, that was not the 
intended use of this flag. 


DDE_FAPPSTATUS 


Reserved for application-dependent return codes 


usFormat 


Is the registered DDE format identifier specified in the original request 
Gif any). 


offszitemName 


Offset to string indicating which item the acknowledgement is for. 


39 In the Windows implementation, WM_DDE_ACK messages 
do not specify which item the acknowledgement is for. 
Rather, the originator must rely on the message synchroni- 
zation rules of DDE and assume that requests are handled 
and responded to in the proper sequence. 


offabData 


Offset to beginning of data. This is the offset from the beginning of the 
memory object to the start of the data portion, if any. This field is only 
valid if cbData is greater than zero (0). Typically, this field is calculated 
regardless of the presence of data, although it is legal for the field to 
contain a value of zero (0). 


flResult (ULONG) 


Zero (0), Reserved value. 
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The default window procedure does not expect to get this message and 
takes no action on it other than to return zero. 


a ‘This message is posted after the acknowledging application 
has received and processed the associated request. 

a If this message is received in response to a WM_DDE_EXE- 
CUTE request, the data portion must contain the original 
command string. 


WM_DDE_ADVISE 


Purpose 


Parameters 


To request an application, be advised whenever the specified data item 
changes. The requesting application is posted WM_DDE_DATA mes- 
sages whenever the specified data item changes. Subsequent 
WM_DDE_DATA messages corresponding to this request may or may 
not contain data. This message is always posted. 


mp! (HWND) 


Window handle of requesting application. 


mp2 (PDDESTRUCT) 


Points to a DDESTRUCT structure. (See “DDESTRUCT” in Appendix 
A for complete details regarding this structure.) 

Caution: Use of undefined fields is application-dependent and may 
cause unpredictable results. 


chData 


Size of the data portion (in bytes, starting at offabData) of this message. 
The contents of this field should be zero (0). Although it would be 
permissible to include data in this message, there are no guidelines on 
how the receiving application should interpret the data. 
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fsStatus 


The requesting application is expected to set this field. The following 
constants are defined as bitmasks in the PMWIN.H header file. To set 
the value in the fsStatus field, a bitwise OR operation is performed on 
this field. For example, 


DDESTRUGT Ddestruct; 
DdeStruct.fsStatus |= DDE_FACKREQ; 


DDE_FACKREQ 


If set, the receiving application is requested to set the 
DDE_FACKREQ bit on all subsequent WM_DDE_DATA 
messages corresponding to this request. 


DDE_FNODATA 


If set, the receiving application does not include the rendered 
data item on subsequent WM_DDE_DATA messages corre- 
sponding to this request. 


usFormat 


Is the registered format identifier, indicating the format in which the 
data is to be rendered. 


offszitemName 


Identifies the name of the data item being requested. This string must 
be null (0x00) terminated. 


offabData 


Offset to beginning of data. This is the offset from the beginning of the 
memory object to the start of the data portion, if any. This field is only 
valid if cbData is greater than zero (0). Typically, this field is calculated 
regardless of the presence of data, although it is legal for the field to 
contain a value of zero (0). 


39 «In the Windows implementation of the DDE protocol, this 
message does not contain a data portion. This portion is 
ignored and discarded if this message is posted to an appli- 
cation executing in a WIN-OS2 session. 
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Return Value 


flResult (ULONG) 


Zero (0), Reserved value. 


Default Processing 


The default window procedure does not expect to get this message and 
takes no action on it other than to return zero. 


Guidelines 


= The receiving application responds with a_ positive 
WM_DDE_ACK message if it can honor the request, or a 
negative WM_DDE_ACK message if it cannot. 

a The response must be posted to the window handle specified 
in message parameter one (mp1). 

= The DDE protocol does not define what the responding ap- 
plication should do if the data item changes during the time 
a WM_DDE_DATA message is posted and a WM_DDE_ACK 
is received. However, it is recommended that the server 
immediately post another WM_DDE_DATA message. 


WM_DDE_DATA 


Purpose 


Notifies an application that a data item has changed or updates an 
application with the rendered data item. This message is always posted. 


Parameters 


mp! (HWND) 
Window handle of the responding application. 


mp2 (PDDESTRUCT) 


Points to a DDESTRUCT structure. (See “DDESTRUCT” in Appendix 
A for complete details regarding this structure. ) 

Caution: Use of undefined fields is application-dependent and may 
cause unpredictable results. 
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chData 


Size of the data portion (in bytes, starting at offabData) of this message. 
If this field is zero, then this is treated as a notification that the value 
of the data item has changed. 


fsStatus 


The requesting application is expected to set this field. The following 
constants are defined as bitmasks in the PMWIN.H header file. To set 
the value in the fsStatus field, a bitwise OR operation is performed on 
this field. For example, 


DDESTRUCT DdeStruct; 
DdeStruct.fsStatus |= DDE_FACKREQ; 
DDE_FACKREQ 


If set, the receiving application is expected to respond with a 
WM_DDE_ACK message after processing this message. 


DDE_FRESPONSE 


If set, this message is in response to a previously issued 
WM_DDE_REQUEST message. If not set, this message is in 
response to a _ previously-established data-link (ie. a 
WM_DDE_ADVISE request). 


usFormat 


This is the registered format identifier indicating the format in which 
the data is rendered. 


offsziltemName 


Identifies the name of the data item being updated. This string must be 
NULL (0x00) terminated. 


offabData 


Offset to beginning of data. This is the offset from the beginning of the 
memory object to the start of the data portion, if any. Typically, this field 
is calculated regardless of the presence of data, although it is legal for 
the field to contain a value of zero (0). 
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Return Value 


flResult (ULONG) 


Zero (0), Reserved value. 


Default Processing 


The default window procedure does not expect to get this message and 
takes no action on it other than to return zero. 


Guidelines 


# If the DDE_FACKREQ flag is set, the receiving application 
responds with a WM_DDE_ACK message after processing 
this message. 

= ‘The response (if any) is posted to the window handle speci- 
fied in message parameter one (mp1). 


WM_DDE_EXECUTE 


Purpose 


Requests that a string of commands be executed on behalf of the re- 
questing application. 


Parameters 


mp] (HWND) 


Window handle of requesting application. 


mp2 (PDDESTRUCT) 


Points to a DDESTRUCT structure. (See “DDESTRUCT” in Appendix 
A for complete details regarding this structure. ) 

Caution: Use of undefined fields is application-dependent and may 
cause unpredictable results. 


chData 


Size of the data portion (in bytes, starting at offabData) of this message. 


Return Value 


Default Processing 


Guidelines 
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fsStatus 


As defined, the DDE protocol does not indicate that status flags are 
applicable to this message. 


usFormat 


Registered DDE format identifier. By default, command strings are 
interpreted in DDEFMT_TEXT format. 


offszitemName 


Not applicable, must be zero. 


offabData 


Offset to beginning of data. Contains a NULL (0x00) terminate ASCII 
text string (the DDEFMT_TEXT format) consisting of one or more 
commands to be executed. 


flResult (ULONG) 


Zero (0), Reserved value. 


The default window procedure does not expect to get this message and 
takes no action on it, other than to return zero. 


» The receiving application responds with a_ positive 
WM_DDE_ACK message if it can honor the request, or a 
negative WM_DDE_ACK message if it cannot. 

# The data portion of the WM_DDE ACK message (either 
positive or negative) must contain the original command 
string. The requesting application compares the command 
string in the acknowledgement to its original request to 
determine which request the acknowledgement is for. 

= The response is posted to the window handle specified in 
message parameter one (mp1). 
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WM_DDE_INITIATE 


Purpose 


Parameters 


Return Value 


Default Processing 


Guidelines 


To request initiation of a DDE conversation. This message is sent to 
all top-level frame windows when an client application issues the 
WinDdelnitiate API. This message is always sent. 


mp! (HWND) 


Window handle of requesting application. 


mp2 (PDDEINIT) 


Points to a DDEINIT structure. (See “DDEINIT” in Appendix A for 
complete details regarding this structure. ) 


fResult (BOOL) 


TRUE Successful completion. 
FALSE Error occurred. 


Memory object identified in mp2 (message parameter 2) is freed and a 
value of zero (0) is returned. 


a The receiving application must free the DDEINIT memory 
object. 

# If a CONVCONTEXT structure is present, the receiving 
application must match application, topic, item, and com- 
mand using the information within this structure (see 
“CONVCONTEXT” in Appendix A for further information). 

= If the specified conversation context information of the re- 
ceiving application differs from that of the requesting appli- 
cation, then the receiving application should provide a 
conversation context indicating its criteria in response 
(when issuing the WinDdeRespond API). 
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a If the szAppName field of the associated DDEINIT struc- 
ture is a zero-length string, then any DDE server application 
can respond. 

se Ifthe szTopic field of the associated DDEINIT structure is a 
zero-length string, then the receiving application responds 
once for each topic the receiving application is willing to sup- 
port. Each response must provide a unique window handle. 


WM_DDE_INITIATEACK 


Purpose 


Parameters 


Return Value 


To acknowledge the initiate request. This message is sent by the receiv- 
ing application to the application that originated the WM_DDE_INITI- 
ATE request, and it is sent when the acknowledging application issues 
the WinDdeRespond API call. This message is always sent. 


mp! (HWND) 
Window handle of acknowledging application. 


mp2 (PDDEINIT) 

Points to a DDEINIT structure. (See “DDEINIT” in Appendix A for 
complete details regarding this structure. ) 

pszAppName 

Pointer to NULL (0x00) terminated ASCII text string containing the 
name of the responding server. It must not be a zero-length string. 
pszlopicName 


Pointer to NULL (0x00) terminated ASCII text string containing the 
name of the topic a server is willing to support. It must not be a 
zero-length string. 


fResult (BOOL) 


This value is returned as the return value to the caller of the WinDdeRe- 
spond API. ATRUE indicates that the responding application wishes to 
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engage in a conversation link. AFALSE value indicates that an error oc- 


curred and the responding application cannot engage in a conversation 
link. 


Default Processing 


Memory object identified in mp2 (message parameter 2) is freed and a 
value of zero (0) is returned. 


Guidelines 
a The receiving application must free the DDEINIT memory 
object. 
WM_DDE_POKE 
Purpose 
Request that the receiving application accept an unsolicited data item. 
This message is always posted. 
Parameters 


mp] (HWND) 


Window handle of requesting application. 


mp2 (PDDESTRUCT) 


Points to a DDESTRUCT structure. (See “DDESTRUCT” in Appendix 
A for complete details regarding this structure. ) 

Caution: Use of undefined fields is application-dependent and may 
cause unpredictable results. 


chData 


Size of the data portion (in bytes, starting at offabData) of this message. 


fsStatus 


As defined, the DDE protocol does not indicate that status flags are 
applicable to this message. 


Return Value 


Default Processing 


Guidelines 
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39 In the Windows implementation of the DDE protocol this 
message does not contain flags. This field is ignored 
when passing this message to an application running in a 
WIN-OS2 session. 


usFormat 


Is the registered format identifier indicating the format in which the 
data is rendered. 


offszitemName 


Identifies the name of the data item to be updated. This string must be 
a NULL (0x00) terminated ASCII text string. 


offabData 


Offset to beginning of data. This is the offset from the beginning of the 
memory object to the start of the data portion. The format of the data 
contained in this portion is defined in the usFormat field of this struc- 
ture. 


flResult (ULONG) 


Zero (0), Reserved value. 


The default window procedure does not expect to get this message and 
takes no action on it other than to return zero. 


» The receiving application responds with a_ positive 
WM_DDE_ACK message if it can honor the request, or a 
negative WM_DDE_ACK message if it cannot. 

# The response is posted to the window handle specified in 
message parameter one (mp1). 
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WM_DDE_REQUEST 


Purpose 


Parameters 


Requests that the receiving application provide the specified data item. 
This message is always posted. 


mp] (HWND) 


Window handle of requesting application. 


mp2 (PDDESTRUCT) 


Points to a DDESTRUCT structure. (See “DDESTRUCT” in Appendix 
A for complete details regarding this structure. ) 

Caution: Use of undefined fields is application-dependent and may 
cause unpredictable results. 


chData 


Size of the data portion (in bytes, starting at offabData) of this message. 
The contents of this field should be zero (0). Although it possible to 
include data in this message, there are no guidelines on how the receiv- 
ing application should interpret the data. 


39 In the Windows implementation of the DDE protocol this 
message does not contain a data portion. This portion is 
ignored and discarded when posting this message to an ap- 
plication executing in a WIN-OS2 session. 


fsStatus 


As defined, the DDE protocol does not indicate that status flags are 
applicable to this message. 


9 In the Windows implementation of the DDE protocol this 
message does not contain flags. This field is ignored 
when posting this message to an application executing in a 
WIN-OS2 session. 


Return Value 


Default Processing 


Guidelines 
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usFormat 


This is the registered format identifier indicating the format in which 
the data is to be rendered. 


offszitemName 


Identifies the name of the data item being requested. This string must 
be NULL (0x00) terminated. 


flResult (ULONG) 


Zero (0), Reserved value. 


The default window procedure does not expect to get this message and 
takes no action on it other than to return zero. 


a The receiving application responds with a WM_DDE_DATA 
message if it can provide the requested data item and a 
negative WM_DDE_ACK message if it cannot. 

=» The response is posted to the window handle specified in 
message parameter one (mp1). 


WM_DDE_ TERMINATE 


Purpose 


Parameters 


Notifies a DDE conversation partner to terminate a conversation link. 
This message constitutes a promise by the originating application that 
it will post no further messages. In addition, this message grants the 
receiving application permission to destroy any resources created in 
support of the conversation link. This message is always posted. 


mp! (HWND) 
Window handle of the originating application. 
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mp2 (MPVOID) 


Zero (0), Reserved value. 


Return Value 


flResult (ULONG) 


Zero (0), Reserved value. 


Default Processing 


The default window procedure does not expect to get this message and 
takes no action on it other than to return zero. 


Guidelines 


WM_DDE_UNADVISE 


Purpose 


Once a WM_DDE_TERMINATE message has been posted, 
the posting application should post no further DDE mes- 
sages to that application. Prior to receiving the correspond- 
ing WM_DDE_TERMINATE message, if the originating 
application receives a DDE message from an application to 
which it has posted a WM_DDE_TERMINATE message, no 
response should be posted. However, it is legal to process the 
message. 

This message can be posted by either a client or server 
application at any time. Similarly, an application must be 
able to process a WM_DDE_TERMINATE message at any 
time. The recipient of aWM_DDE_TERMINATE message is 
expected to post a WM_DDE_TERMINATE message in re- 
sponse. It is not permissible to respond with a negative, busy, 
or positive WM_DDE_ACK message. 

An application must post a WM_DDE_TERMINATE mes- 
sage to each of its conversation partners before it terminates. 
The response is posted to the window handle specified in 
message parameter one (mp1). 


Requests that updates and/or notification no longer be posted for the 
specified data item. This message is always posted. 


Parameters 


APPENDIX B / DDE MESSAGES 129 


mp] (HWND) 


Window handle of requesting application. 


mp2 (PDDESTRUCT) 


Points to a DDESTRUCT structure. (See “DDESTRUCT” in Appendix 
A for complete details on this structure. ) 

Caution: Use of undefined fields is application dependent and may 
cause unpredictable results. 


chData 


Size of the data portion (in bytes, starting at offabData) of this message. 
The contents of this field should be zero (0). Although it possible to 
include data in this message, there are no guidelines on the receiving 
application interpreting the data. 


3 «In the Windows implementation of the DDE protocol this 
message does not contain a data portion. This portion is 
ignored and discarded if posting this message to an applica- 
tion executing in a WIN-OS2 session. 


fsStatus 


As defined, the DDE protocol does not indicate that status flags are 
applicable to this message. 


38 «In the Windows implementation of the DDE protocol this 
message does not contain flags. This field is ignored if posting 
this message to an application executing in a WIN-OS2 ses- 
sion. 


usFormat 


Is the registered DDE format identifier indicating in which format the 
receiving application can discontinue automatic data updates. If this 
value is zero, then the receiving application discontinues all active 
data-links associated with the specified item. 
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offszitemName 


NULL (0x00) terminated ASCII text string identifying which data item 
data updates are to be discontinued. If this is a zero-length string, then 
receiving application will discontinue all active data-links associated 
with the conversation link. 


Return Value 


flResult (ULONG) 


Zero (0), Reserved value. 


Default Processing 


The default window procedure does not expect to get this message and 
takes no action on it other than to return zero. 


Guidelines 


= The receiving application responds with a_ positive 
WM_DDE_ACK message if it can honor the request, or a 
negative WM_DDE_ACK message if it cannot. The response 
is posted to the window handle specified in message parame- 
ter one (mp1). 


WinDdelnitiate 


Invocation 


Appendix C 


DDE Functions 


This appendix describes each DDE function. 


This function is issued by an application to request initiation of a DDE 
conversation link. This function sends a WM_DDE_INITIATE message 
to all top-level frame windows. A top-level frame window is a window 
registered with a CS_FRAME class style and whose parent is the 
desktop window. No messages are sent to object windows. 

This function does not return to the calling application until all top- 
level frame windows have, in sequence, processed the WM_DDE_INITI- 
ATE message, and the calling application has received and processed all 
corresponding WM_DDE_INITIATEACK messages (see WinDdeRe- 
spond). 

This function creates a DDEINIT structure, fills it in with the pa- 
rameters supplied, and passes a pointer to this structure in message 
parameter 2 (mp2) of the WM_DDE_INITIATE message. 

The calling thread must have created a message queue prior to 
issuing this function call. 


Use the following statement(s) to include definitions required for this 
function: 


4#HKdefine INCL_WINDDE -or- +#define INCL_WIN 
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Prototype 


Parameters 


Return Value 
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BOOL WinDdeInitiate ( HWND hwndClient 
PSZ pszAppName 
Paz pszlopicName 


PCONVCONTEXT pContext 


hwndClient 


Requesting applications window handle. 


pszAppName 


Application name. This is the name of the desired server application. If 
it is a zero-length string, any server application can respond. This 
parameter must point to a valid string; it cannot be a NULL. Applica- 
tion names may not contain slashes or back-slashes. 


pszlopicName 


Topic name. This is the name of the desired topic. If it is a zero-length 
string, the responding application will respond once for each topic it can 
support. This parameter must point to a valid string; as in 
pszAppName, it cannot be a NULL value. 


pContext (optional) 


Pointer to a CONVCONTEXT (conversation context structure). If no 
CONVCONTEXT structure is required, this parameter can be a NULL 
value. 


fResult (BOOL) 


TRUE Function successfully completed. 
FALSE An error occurred. 


Note: Two possible conditions exist that would cause PM to abort this 
API: 


a Hither pszAppName, pszTopicName or both where specified 
with a NULL value. 
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# Ashared memory object large enough to contain a DDEINIT 
structure could not be allocated. 


Guidelines 


a pszAppName and pszTopicName cannot be NULL. If a name 
is not desired, then these fields must contain a pointer to a 
zero-length ASCII text string. 

a» ACONVCONTEXT structure should be included, although 
it is not required. 


WinDdePostMsg 


The WinDdePostMsg API is used to deliver DDE transaction mes- 
sages. The calling thread must have created a message queue prior to 
issuing this function call if the DDEPM_RETRY option is specified. 


Invocation 


Use the following statement(s) to include definitions required for this 
function: 


4tdefine INCL_WINDDE -or- #define INCL_WIN 


Prototype 


MRESULT WinDdePostMsg ( HWND hwndTo 
, HWND hwndFrom 
, USHORT usMsgld 
, PDDESTRUCT pData 
ULONG ulOptions 


hwndTo 
Window handle of target application. 


hwndFrom 


Window handle of originating application. 
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usMsgld 


Message identifier. The following are valid messages: 


pData 


WM_DDE_ACK 
WM_DDE_ADVISE 
WM_DDE_DATA 
WM_DDE_EXECUTE 
WM_DDE_POKE 
WM_DDE_REQUEST 
WM_DDE_TERMINATE 
WM_DDE_UNADVISE 


Pointer to a shared memory object containing a DDESTRUCT struc- 
ture and any additional information. 


ulOptions 


Message delivery options. 


DDEPM_RETRY 


In the event a message cannot be posted because the desti- 


nation message queue is full, this option indicates that 
WinDdePostMsg should retry posting the message at one- 
second intervals. An application will continue to receive 
messages while waiting for the DDE message to be posted. 
If this option is not set, or the posting fails for any other 
reason than a full message queue, this function returns 
FALSE without retrying. If the post fails for any other rea- 
son other than a full message queue, this function returns 
FALSE. 


DDEPM_NOFREE 
Indicates that the DDESTRUCT structure reference by the 


pData parameter should not be freed by this function. This 
is useful if an application wishes to reuse the DDESTRUCT 
structure. For example, an application needs to acknowledge 
several requests. It can create the DDESTRUCT once and 
use it in server calls to this API. If this option is not set, the 
DDESTRUCT reference by the pData parameter is freed in 
the calling process by this API. 


Return Value 


Guidelines 


WinDdeRespond 


Invocation 


Prototype 


fResult (BOOL) 
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TRUE Message was successfully posted to the server’s mes- 


sage queue. 


FALSE An error occurred and the message was not posted to 


the server’s message queue. 


Possible error conditions are as follows: 


The window handle identified in hwndTo or hwndFrom is no 
longer valid. 

The DDESTRUCT structure could no be given to the receiv- 
ing application. 

The message identifier was not in the range 
WM_DDE_FIRST to WM_DDE_LAST. 


In the event of an error, an application should use WinGet- 
LastError for further information. 


This function is issued by a server application in a positive response to 
a WM_DDE_INITIATE message. This function creates a DDEINIT 
structure, fills it in with the parameters supplied, and passes a pointer 
to this structure in message parameter 2 (mp2) of the WM_DDE_INITI- 
ATEACK message. 


The calling thread must have created a message queue prior to 


issuing this function call. 


Use the following statement(s) to include definitions required for this 
function: 


#define INCL_WINDDE -or- #define INCL_WIN @LEND = 


MRESULT WinDdeRespond ( HWND hwndClient 


HWND hwndServer 

PSZ pszAppName 

PSZ pszTopicName 
PCONVCONTEXT pContext 
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Parameters 


Return Value 
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hwndClient 


Client’s window handle. This must be the same window handle specified 
in message parameter one (mp1) of the WM_DDE_INITIATE message. 


hwndServer 


Server window handle. This window handle must be unique for each 
response. This guarantees that a unique window handle pair exists for 
each established conversation. Typically, a server creates this window 
as invisible. 


pszAppName 


Application name. This is the name of the desired server application. 
This parameter must point to a valid string; it cannot be a NULL. 
Application names may not contain slashes or back-slashes. A server 
application fills in this field if a WM_DDE_INITIATE message was 
received with a zero-length string. 


pszlopicName 


Topic name. This is the name of the supported topic. This parameter 
must point to a valid string; it cannot be a NULL value and should 
contain a non-zero-length string. A server application fills in this field if 
a WM_DDE_INITIATE message was received with a zero-length string. 


pContext 


Pointer to a CONVCONTEXT (conversation context structure). If the 
requesting application did not supply a CONVCONTEXT structure in 
its initiation request, or if the context of the server does not match that 
of the requesting application, a server application should supply one in 
its response. 


mResult (MRESULT) 


This is the same value returned by an application in response to a 
WM_DDE_INITIATEACK message. 


Guidelines 
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TRUE Receiving application accepts the acknowledgement 
and a conversation link is established. If, after accepting this 
acknow- edgement, the receiving application determines that 
the conversation is unwanted, it must terminate the conver- 
sation link. 

FALSE An error occurred, or the receiving application does 
not want to engage in a conversation link. The receiving 
application must still post a WM_DDE_TERMINATE mes- 
sage for any unwanted conversation links. 


# The hwndClient parameter must be the same window han- 
dle that was specified in message parameter one (mp1) of the 
WM_DDE_INITIATE message. 

a The hwndServer must provide a unique window handle; that 
is, in each response, the server must provide a different 
window handle. Typically, this window is created as invis- 
ible. 

= Aserver should include a CONVCONTEXT structure in its 
response if either no CONVCONTEXT structure was pre- 
sent in the WM_DDE_INITIATE message or the contents of 
the structure did not match those of the responding server. 
For example, the server’s codepage is different from that of 
the requesting client application. 


Appendix D 


DDE Macros 


This section describes the DDE helper macros defined in the PMWIN.H 
header file. These macros, like any other DDE-related DDE definition, 
can be included in an application by specifying the following statement 
before the inclusion of the OS/2.H header file: 


#define INCL_WINDDE 


DDEI_PCONVCONTEXT 


Guidelines 


#define DDEI_PCONVCONTEXT(pddei) \ 
((PCONVCONTEXT)((PBYTE)pddei + pddei->offConvContext) ) 


Given a pointer to a DDEINIT structure, the macro first gets the 
address to the beginning of the DDEINIT structure, then adds the 
offset of the CONVCONTEXT structure, and returns the resulting 
address. The following code fragment illustrates the use of this macro: 


PCONVCONTEXT pCC = DDEI_PCONVCONTEXT (pDdelnit); 


= The pointer (address) returned is valid only if the offConv- 
Context field of the DDEINIT structure contains a non-zero 


value. A non-zero value indicates that a CONVCONTEXT 
structure exists. 
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DDES_PABDATA 


#tdefine DDES_PABDATA(pddes) \ 
(((PSZ)pddes) + ((PDDESTRUCT )pddes)->offabData) 


Given a pointer to a DDESTRUCT structure, the macro first gets the 
address to the beginning of the DDESTRUCT structure, adds the offset 
to the data portion, and returns the resulting address. The following 
code fragment illustrates the use of this macro: 


PBYTE pbData = (PBYTE) DDES_PABDATA (pDdeStruct); 


Guidelines 


a ‘I'he pointer (address) returned is valid only if the cbData 
field of the DDESTRUCT contains a non-zero value. A non- 
zero value indicates that data exists. 


DDES_PSZITEMNAME 


#Fdefine DDES_PSZITEMNAME(pddes ) \ 
(((PSZ)pddes) + ((PDDESTRUCT )pddes)->offszItemName) 


Given a pointer to a DDESTRUCT structure, the macro first gets the 
address to the beginning of the DDESTRUCT structure, adds the offset 
to the item name-string, and returns the resulting address. The follow- 
ing code fragment illustrates the use of this macro: 


PSZ pszItemName = (PSZ) DDES_PSZITEMNAME (pDdeStruct) ; 


Guidelines 


=» The pointer (address) returned is valid only if the offszltem- 
Name field of the DDESTRUCT structure contains a non- 
zero value. A non-zero value indicates that a NULL (0x00) 
terminated string exists. 

# It is legal to have a zero-length string starting at this loca- 
tion. 


Appendix E 


DDE Status Flags 


DDE status flags control various aspects of a DDE transaction. DDE 
status flags are defined as unique bitmask values in the PMWIN.H 
header file. Flags can be combined using the bitwise OR operator. The 
following code fragment shows how to two flags can be combined. The 
result of this operation is then placed in the fsStatus field of a DDE- 
STRUCT structure. 


DDESTRUCT DdeStruct; 
DdeStruct.fsStatus |= (DDE_FACK | DDE_FRESPONSE); 


A flag is said to be on if the bits corresponding to the defined bitmask 
for the flag are set to one (1). A flag is said to be off if the bits 
corresponding to the defined bitmask for the flag are set to zero (0). 
Some flags are valid if and only if another flag is set on or off. For 
example, the DDE_FBUSY flag is valid only if the DDE_FACK flag is 
set off. An application uses the AND operator to determine if a flag is 
set on, as illustrated in the following code fragment: 


PDDESTRUCT pDdeStruct 
BOOL fPosAck 


(PDDESTRUCT) PVOIDFROMMP (mp2); 
(BOOL) pDdeStruct->fsStatus & DDE_FACK; 


In the following definitions, the bitmask for the flag is declared in 
brackets; for example, [0x0001] is the bitmask for the DDE FACK 
status flag. 


14] 
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DDE_FACK 


DDE_FACKREQ 


DDE_FAPPSTATUS 


Acknowledgement flag [0x0001] This flag is valid only in the context 
of a WM_DDE_ACK message. If set on, this is a positive acknow- 
ledgement. If set off, this is a negative acknowledgement. The following 
code fragment will set the variable fPosAck to TRUE if this flag is set 
on, and to FALSE if this flag is set off. 


BOOL fPosAck = (BOOL) pDdeStruct->fsStatus & DDE_FACK; 


Request Acknowledgement flag [0x0008] This flag is valid only in the 
context of aWM_DDE_REQUEST or WM_DDE_ADVISE message. 

If set on, the receiving application is requested to respond with a 
WM_DDE_ACK message after processing the message. 

If the context of a WM_DDE_ADVISE message, this flag indicates 
that the DDE_FACKREQ flag should be set on, in subsequent 
WM_DDE_DATA messages corresponding to the advise request. This 
offers flow-control in which a server application does not post another 
WM_DDE_DATA message until it receives an acknowledgement from 
the previous WM_DDE_DATA message. This prevents a client’s appli- 
cation queue from being filled if messages arrive faster than the client 
can process them. 

In the context of aWM_DDE_ REQUEST message, this flag indicates 
that the server should post a WM_DDE_ACK message upon receipt of 
the message. The following code fragment will set the variable fPosReq 
to TRUE if this flag is set on, and to FALSE if this flag is set off. 


BOOL fAckReq = (BOOL) pDdeStruct->fsStatus & DDE_FACKREQ; 


Application Status flag [OxFF00] This flag is valid only in the context 
of aWM_DDE_ACK message. 

The upper 8 bits of the fsStatus field are reserved for application-spe- 
cific information. An application can mask off any status flags by per- 
forming an AND operation on the fsStatus field with this flag. The 
results of the AND operation is the application-specific status. For 
example: 


BYTE bAppStatus = pDdeStruct->fsStatus & DDE_FAPPSTATUS; 


DDE_FBUSY 


DDE_FNODATA 


DDE_FRESERVED 
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If more than 8 bits are required by a server application, the server 
should provide this additional information by supporting the 
SZDDE_SYS_RTNMSG data item of the System topic. (See “System 
Topic” for more information regarding this data item.) 


Busy flag [0x0002] This flag is valid only in the context of a 
WM_DDE_ACK message. 

If set on, the acknowledging application is busy and cannot satisfy the 
request. A server should update the following System topic items in 
support of setting this flag: 


SZDDE_SYS_RTNMSG 
SZDDE_ITEM_STATUS 


The following code fragment will set the variable fBusy to TRUE if 
this flag is set on, and to FALSE if this flag is set off. 


BOOL fBusy = pDdeStruct->fsStatus & DDE_FBUSY; 


Post/Receive No Data flag [0x0004] This flag is valid only in the con- 
text of aWM_DDE_ADVISE or WM_DDE_DATA message. 

If set on, in the context of a WM_DDE_ADVISE message, this flag 
indicates that subsequent WM_DDE_DATA messages are to be posted 
with a zero-length data portion. In addition, the cbData field should be 
set to zero (0) and the DDE_FNODATA status flag should be set. 

This type of WM_DDE_DATA message functions as notification to the 
client that the data item changed (commonly known as a warm-link). 
(See the “Advise” transaction, Chapter 4, for further information re- 
garding this type of data-link.) The following code fragment will set the 
variable fNoData to TRUE if this flag is set on, and to FALSE if this flag 
is set off. 


BOOL fNoData = pDdeStruct->fsStatus & DDE_FNODATA; 


Reserved flag [0Ox000C] Reserved for future use. 
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DDE_FRESPONSE 


Response Flag [0x0010] This message is only valid in the context of a 
WM_DDE_DATA message. 

If set on, this flag indicates that this message is in response to a 
previous WM_DDE_ REQUEST message. A client uses the presence of 
this flag to differentiate between WM_DDE_DATA messages resulting 
from a previous request or Advise transaction. The following code frag- 
ment will set the variable fResponse to TRUE if this flag is set on, and 
to FALSE if this flag is set off. 


BOOL fResponse = pDdeStruct->fsStatus & DDE_FRESPONSE; 


DDE_NOTPROCESSED 


Not Processed flag [0x0020] This flag is only applicable in the context 
of aWM_DDE_ACK message. 

If set on, this flag indicates that the previous request is not supported 
and the request was ignored by the receiving application; for example, 
a server does not support the WM_DDE_ADVISE message for a particu- 
lar data item. 

It is legal to set this status flag on a negative WM_DDE_ACK mes- 
sage. Although not the intended purpose of the flag, it is not considered 
an error if present. The following code fragment will set the variable 
fNotProcessed to TRUE if this flag is set on, and to FALSE if this flag is 


set off. 


BOOL fNotProcessed = pDdeStruct->fsStatus & DDE_NOTPROCESSED; 


Appendix F 


DDE Library 


This section lists various functions to help simplify the implementation 
of the DDE protocol in an application. 


/ * 
Kk 
a= PUNT ONS DdeMakeDdeStruct 
*x* 
** Usage: Allocates and initializes a shared memory object. 
*K* 
PDDESTRUCT /* pointer to DDESTRUCT structure a | 
APITENTRY DdeMakeDdeStruct 
( 
PSZ pszItemName /* pointer to item name-string ae | 
, PVOID pvData /* pointer to rendered data (if any) af i 
, ULONG cbData /* size of rendered data (if any) my 
, USHORT usFormat /* registered DDE format identifier alt 
, USHORT fsStatus J/* DDE Status flags * J 
) 
APIRET ApiRet; 
USHORT cbIltemName; 
PDDESTRUCT pDdeStruct; 
PSZ pszNul | =“ 


** If a NULL value is passed in as a pointer to an Item name, then set 
*x pszitemName to point to a NULL terminated string. This guarantees that 
*k the pszItemName always points to a NULL (0x00) terminated string. 
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a 


/* 


*x* 


oe 


/* 


kK* 


= 


/* 


kx 


a | 


/* 


K* 


vf 


/* 


kK* 


mp 


/* 


kK* 


oe 
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if (pszItemName == (PSZ) NULL) 
pszItemName = pszNull; 
Calculate the size of the Item name (including the NULL character)... 


cbItemName = strlen (pszItemName) + IL; 


Allocate shared memory object... 


ApiRet = DosAllocSharedMem 
( (PPVOID) &pDdeStruct /* base address of shared memory object 
» (PSZ) NULL /* un-named memory object 
, sizeof (DDESTRUCT) /* size of memory object (in bytes), 
+ cbItemName /* size of item name-string, 
+ cbData /* size of data (if any), 
, PAG_COMMIT /* all pages are initially committed 
| OBJ_GIVEABLE /* memory object is giveable 
| PAG_READ /* read access allowed 
| PAG_WRITE /* write access allowed 
15 


If shared memory object creation failed, return NULL pointer... 


if (ApiRet != NO_ERROR) 
{ 

return ((PDDESTRUCT) NULL); 
} 


Initialize shared memory object... 


pDdeStruct->cbData = cbData; 
pDdeStruct->fsStatus = fsStatus; 
pDdeStruct->usFormat usFormat; 
pDdeStruct->offszItemName = sizeof (DDESTRUCT); 


pDdeStruct->offabData = sizeof (DDESTRUCT) + cbItemName; 
Copy Item name-string to shared memory object... 
pszNull = memcpy 
( DDES_PSZITEMNAME (pDdeStruct) 
, pszIitemName 
, cbItemName 
3 
If rendered data exists, copy data to shared memory object... 


ks 
a 
=} 
my 
ur 
wf 
ae 
wy 
aed 


xx 


a 
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if (pvData && cbData) 


pszNull 


= memcpy 


( DDES_PABDATA (pDdeStruct) 
, pvData 
cbData 


Return pointer to shared memory object containing DDESTRUCT structure... 


return ((PDDESTRUCT) pDdeStruct); 
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PLUNGE On* 


Usage: 


BOOL 
APIENTRY 


Poe 
PSL 
ULONG 
ULONG 
ULONG 


ULONG 
ULONG 
CHAR 
CHAR 


s* TResult: Error lacicater 
DdeCompareStrings 
pSZStringl /* pointer to null terminated string 
pszString2 /* pointer to null terminated string 
fCaseSensitive /* compares are case sensitive: TRUE/FALSE 
ulCountry /* country code used in comparisons 
ulCodepage /* codepage used in comparisons 
flResult; 
epStri ngs 


DdeCompareStrings 


Compares two strings with sensitivity to case, country and 
codepage. 


SZSTRING] [LMAX_TEXTLENGTH]; 
SZSTRING2 LMAX_TEXTLENGTH]; 


If comparison of strings is not casesensitive, then convert each string 
to uppercase. This allows for a mixed-case strings to be compared 


equally. 


if (!fCaseSensitive) 


{ 


Make a copy of stringl and string2. This allows us to convert the 
strings to upper case while preserving the original strings... 


pszstringl = strcpy /* copy a null (0x00) terminated string... 


( (PSZ) szSTRING1 /* to this location, 


al 3 
mf 
ef 
oF 
my 


sal 
dj 
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, pszstringl c* FROM TNs 1Ocation. al | 
i 
pszString2 = strcpy /* copy a null (Ox00) terminated string...*/ 
( (PSZ) szSTRING2 /* to this location, my 
» PSzSiring2 /* Trom this 10cation. * f 
i 
/* 
we Convert stringl to upper case... 
oe 
cbString = WinUpper /* convert a string to uppercase “y 
( hab /* handle to anchor block at | 
, ulCodepage /* codepage identifier xf 
, ulCountry /* country identifier oF 
» {PSZ) SZSTRINGL #* location of string ta convert ae 
ie 
/* 
ae If the string could not be converted, return indicating failure... 
mf 
if (cbString == 0) 
{ 
return (FALSE); 
} 
/* 
ae Convert stringl to upper case... 
ial 
cbString = WinUpper /* convert a string to uppercase ok | 
( hab /* handle to anchor block m 
, ulCodepage /* Codepage identifier ae 
, ulCountry /* Country identifier a} 
» (PSZ) szSTRING2 /* location of string to convert kj 
i 
/* 
al if the string could not be converted, return indicating failure... 
a 
if (cbString == 0) 
return (FALSE); 
/* 
os Compare SLFIngs..«:. 
* if 
flResult = WinCompareStrings 
( hab /* Anchor-block handle at | 
, ulCodepage /* Code page identity of both strings mf 
, ulCountry /* Country code identity of both strings */ 
, PSZStrindl /* Pointer to first comparison string | 
« BSZ5T Ri 1GzZ /* Pointer to second comparison string otf 


, OL /* Options: Not used must be zero (0) ar i 


/* 


LE 
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** Check the result of the comparison... 


td 


/* 


xK* 


7 


/* 


K* 


at | 


/* 


K* 


a 


1f (7 iResuit — WCS_FQ) 


/* if strings were equal... 


return (TRUE); 


} 
else 
{ 


return (FALSE); 
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a 


Usage: 


HBITMAP 
APTENTRY 


ie 
PODES [| RUGT 


BOOL 
USHORT 
USHORT 
HBITMAP 
RECTL 
Poe 


DdeCreateBitmap 


Creates a bitmap from data in a DDESTRUCT structure. 


/* Handle of Bitmap 
DdeCreateBitmap 


hps /* handle to presentation-space 
pDdeStruct /* address of DDESTRUCT structure 


fResult; 

cColors = 1; 

CDRGB; 

hbmp = NULLHANDLE; 
Pets 

pbData; 


Establish pointers to required bitmap structures... 


PBITMAPINFO pbmi 
PBI TMAPINFO2 pbmi2 


= (PBITMAPINFO) DDES_PABDATA (pDdeStruct) ; 
(PBITMAPINFO2) DDES_PABDATA (pDdeStruct) ; 


Check that bitmap data exists... 


if (pDdeStruct->cbData) 


Check if bitmap data is in 1.2 format... 


if € POMi--corIxX = iz ) 
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/* 
sl Determine the number of colors supported... 
Kx 
i Note: If the bitmap is 24-bits per/pel then no color table exists... 
* 
if (pbmi->cBitCount != 24) 
cColors <<= pbmi->cBitCount; 
/* 
a Calculate color table information... 
= 
CcDRGB = cColors * ( (USHORT) sizeof (RGB) ); 
pbData = (PBYTE) &(pbmi->argbColor); 
pbData += cCDRGB; 
/* 
ls Create a bitmap from the given data... 
mf 
hbmp = GpiCreateBitmap 
( hps /* handle Presentation-space i 
, (PBITMAPINFOHEADER2) pbmi /* bit-map information header a 
, CBM_INIT /* initialize the bitmap af 
, pbData /* buffer address xi 
, (PBITMAPINFO2) pbmi /* bit-map information table =f 
3 
/* 
iat Otherwise bitmap data is in 2.0 format... 
mf 
else 
/* 
sli Determine the number of colors supported... 
*K* 
liad Note: If the bitmap is 24-bits per/pel then no color table exists... 
soft 
if (pbmi2z->cBitCount != 24) 
cColors <<= pbmi2->cBitCount; 
/* 
ae Calculate color table information... 
a 
cbDRGB = cColors * ( (USHORT) sizeof (RGB2) ); 
pbData = (PBYTE) &(pbmi2->argbColor); 
pbData += cCDRGB; 
/* 
tel Create a bitmap from the given data... 


ey 
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hbmp = GpiCreateBitmap 


( hps /* handle Presentation-space mf 
» (PBITMAPINFOHEADER2) pbmi2 /* bit-map information header ad | 
, CBM_INIT /* initialize the bitmap =7 
, pbData /* buffer address a | 
, pbmi2 /* bit-map information table a 
4 
} 

/* 

** Return resulting bitmap handle... 

at 


return (hbmp) ; 


/ kaeeeaa ease a SSeS SS SS SS SS SS SS SS SS SS SS SS SS SS SS SS 5 5 5 SS 555555 =5=== 
kx 
we Funct on: DdeCreateMetafile 
K* 
wm ISA Ces Creates a metafile from data in a DDESTRUCT structure. 
kx 
HMF /* Metafile handle aj 
APTENTRY DdeCreateMetafile 
( 
HPS hps /* handle to presentation-space al | 
» PDDESTRUCT pDdeStruct /* address of DDESTRUCT structure = 
) 
#tdefine COUNT_OPTIONS (LONG) (PMF_DEFAULTS + 1) 
define LDESC 256L 
BOOL fResult = FALSE; 
HMF hmf ; 
HDC nde: 
PBYTE DMFData = (PBYTE) DDES_PABDATA (pDdeStruct) ; 
DEVOPENSTRUC dop; 
/ * 
** Initialize ‘Device Open Structure’... 
ae 
dop.pszLogAddress = NULL; /* logical address * 
dop.pszDriverName = “DISPLAY”; /* driver name wl i 
dop.pdriv = NULL; /* DRIVDATA structure ar | 
dop.pszDatalype = NULL; /* data type a J 
dop.pszComment es ULL: /* any comments = 
dop.pszQueueProcName = NULL; /* use default wy 
dop.pszQueueProcParams = NULL; /* no parameters required ae | 
dop.pszSpoolerParams = NULL; /* no parameters required mi 


dop.pszNetworkParams = NULL; /* not used =f 
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/* 


xk* 


a 


/* 


xK* 


*y 


/* 


K* 


Ps 


/* 


*xK* 


*/ 


/* 


xK* 


ar 


/* 


K* 


ey 
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Open a *Metafile’ compatible Device Context... 


hdc = DevOpenDC /* Create a Device context 
( hab /* Handle to Anchor-block 
, OD_METAFILE /* Context used to hold metafiles 
oo /* No device info from init file 
, OL /* # of items in pdopData parameter 

(PDEVOPENDATA) &dop /* Open device context data area 

» (HDC) NULL /* Context compatible with screen 
y% 


If DC failed to be opened... 


if (hdc == DEV_ERROR) 
{ 

return (NULLHANDLE); 
} 


Close the DC to obtain a handle to the empty metafile... 


hmf DevCloseDC 
h 


( hdc /* handle to metafile compatible DC 
a 


If closure failed, return indicating failure... 
if (hmf == DEV_ERROR) 
{ 


return (NULLHANDLE); 
} 


Set the metafile-bits into the empty metafile 


fResult = GpiSetMetaFileBits 


( hmf /* handle to empty metafile 

- OL /* offset into metafile to begin 
, pDdeStruct->cbData /* length of metafile data 

, PMFData /* address of metafile data 


ie 
If Metafile-bits successfully set... 


if (fResult) 
{ 
BYTE abDesc L LBESG I 
LONG alOptions [COUNT_OPTIONS]; 
LONG ]SegCount; 
SILZEL. -Sizls 


a 
| 
at 
a) 
a 
iat | 
a 


ay 


at | 
i 
iad 
a | 
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alOptions [PMF_SEGBASE] = OL; 
alOptions [LPMF_LOADTYPE] = LT_ORIGINALVIEW; 
alOptions [LPMF_RESOLVE] = UL: 
alOptions [PMF_LCIDS] = (CC LOADDISC: 
alOptions LPMF_RESET I = RES_RESET; 
alOptions [LPMF_SUPPRESS] = SUP_SUPPRESS; 
alOptions [LPMF_COLORTABLES] = CTAB_REPLACE; 
alOptions [PMF_COLORREALIZABLE] = CREA_DEFAULT; 
alOptions [PMF_DEFAULTS] = DDEF_DEFAULT; 
/* 
we Play the Metafile into the specified Presentation Space... 
*} 
fResult = (BOOL) GpiPlayMetaFile 
( hps /* handle of Presentation Space a) 
, hmt /* handle of Metafile sa 
, COUNT_OPTIONS /* count of optiens ats 
, alOptions /* |ist of options ca 
» &lSegCount /* reserved, zero always returned <p 
LDESC /* length of bytes in ’abDesc’ a | 
, abDesc /* descriptive record * 
rs 
} 
/* 
*x Return resulting Metafile handle... 
xf 


return (hmf); 


[SSS SSS SS SS SS SSS 
*K* 
** Function: DdeExecuteCommands 
*K* 
ax Usage: Execute a string of commands contained in a CF_TEXT buffer. 
*x* 
BOOL /* fResult: Success indicator all 
APIENTRY DdeExecuteCommands 
( 
HWND hwndServer /* desired server window handle % } 
HWND hwndClient /* requesting window handle * 
USHORT usFormat /* desired format a 
PVOID pvData /* pointer to data ia 
, ULONG cbData /* size of data (in bytes) * if 
) 
{ 
BOOL fResult = FALSE; 
PDDESTRUCT pDdeStruct = NULL; 
/ * 


** Create a DDE shared memory object... 
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st 
pDdeStruct = DdeMakeDdeStruct /* create a shared memory object */ 
( NULL /* item name-string (not applicable) * } 
, pvData /* pointer to data * J 
, cbData /* size of data (in bytes) * 
, DDEFMT_TEXT /* text format * f 
» O /* DDE status flags (not applicable) * 
i 
/* 
** If shared memory object successfully created... 
al J 
if (pDdeStruct) 
{ 
fResult = WinDdePostMsg /* post a DDE message to... * 
( hwndServer f* this requesting window handle, * / 
, hwndClient c= from this responding window handle, */ 
, WM_DDE_EXECUTE j* an “Execute” message, a 
, pDdeStruct [* as defined in this memory object, * 
, DDEPM_RETRY pm and retry if receiving queue is full.*/ 


i 
} 
return (fResult); 


/ Ka 

oe FUNCLION: DdeRegisterFmt 

*K* 

“x Sage: Registers DDE format string with system atom-table. 

*K* 

** Remarks: DDE format name-strings are added to the atom table to 

we ensure that the count associated with the format name-string 

a Stays greater than zero. If we were to query the atom table for 

ts a match on the format name-string and only add the format-name 

me String if it was not found, it would be possible that the usage 

es count for the atom would go to zero while we were still using it. 

oe The would occur if the application (possibly another DDE server 

wn or client) that added it then deleted it; a very bad situation. 

*K* 

== ee / 
USHORT /* Atom identifier a J 
APIENTRY DdeRegisterFmt 

( 
HATOMTBL hAtomTlable /* handle atom-table * 
PSZ pszFormatName /* DDE format name-string se 


return ((USHORT) WinAddAtom (hAtomTable, pszFormatName) ); 
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PUACTION: DdeUnRegisterFmt 


Usage: De-registers DDE format string with system atom-table. 


BOOL /* fResult: Error indicator 
APIENTRY DdeUnRegisterFmt 


HATOMTBL hAtomlable /* handle atom-table 
USHORT usFormatld /* previously registered atom-identifier 
ATOM atom; 


Delete the specified atom-identifier... 


atom = WinDeleteAtom /* Delete an atom from an Atom-table 
( hAtomTable /* Handle of atom-table 
»(ATOM) usFormatlid /* Identifier of Atom to be deleted 
ye 

If WinDeleteAtom was successful, atom will have a value of zero (0). 


If WinDeleteAtom was unsuccessful, atom will contain a value equal to 
usFormatId. Depending on contents of the atom variable, return TRUE if 
the atom was successfully deleted, otherwise return FALSE 


return (atom) ? FALSE : TRUE; 


Function: DdePokeData 
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a 
ar | 
a 


Usage: Poke data to DDE ’Client’ window. 

BOOL /* fResult: Success indicator 
APIENTRY DdePokeData 

HWND hwndServer /* desired server window handle 
HWND hwndClient /* requesting window handle 

PSZ pszItemName /* desired item name-string 
USHORT usFormat /* desired format 

PVOID pvData /* pointer to data 

ULONG cbData /* size of data (in bytes) 

BOOL fResult = FALSE: 


PDDESTRUCT pDdeStruct NULL; 
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/* 
** Creates a DDE shared memory object... 
co | 
pDdeStruct = DdeMakeDdeStruct /* create a shared memory object Lr | 
( pszItemName /* null (0x00) terminated ASCII string ef 
, pvData /* pointer to data my 
, cbData /* size of data (in bytes) * / 
, USFornat /* registered DDE format identifier “ 
, 0 /* DDE status flags (not applicable) * / 
, 
/* 
*x If shared memory object successfully created... 
ol | 
if (pDdeStruct) 
{ 
fResult = WinDdePostMsg /* post a DDE message to... */ 
( hwndServer /* this requesting window handle, | 
, NhwndClient {* from this responding window handle, */ 
, WM_DDE_POKE }® a “Poke” message, ad | 
, pDdeStruct [* as defined in this memory object, *y 
, DDEPM_RETRY {* and retry if receiving queue is full.*/ 


 E- 
} 
return (fResult); 


/ ksaeeaa ses ee ee Se SSS SS SSS SSS SSS SSS SSS SSS SS SS SSS SSS SSS SSS SSS SSS SESS = 

** 

ee FUNCTION: DdeRequestColdLink 

K* 

** Usage: Requests a data item from a DDE ’Server’ window. 

K* 

Sane ae ee a a SS SS SS ee | 
BOOL /* fResult: Success indicator * 
APIENTRY DdeRequestColdLink 

( 

HWND hwndServer /* desired server window handle a 

, HWND hwndClient /* requesting window handle a 

, PSZ pszItemName /* desired item name-string ol 

, USHORT usFormat /* desired format «i 

) 

{ 

BOOL fResult = FALSE; 
PDDESTRUCT pDdeStruct = NULL; 

/* 

** Creates a DDE shared memory object... 

bal 
pDdeStruct DdeMakeDdeStruct /* create a shared memory object at d 


( pszItemName /* null (0x00) terminated ASCII string a 
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, NULL /* pointer to data (not applicable) all 
. Ok /* size of data (in bytes) mf 
, usFormat /* registered DDE format identifier * 
» 2 /* DDE status flags (not applicable) * 
if 

/* 

**x If shared memory object successfully created... 

* i 

if (pDdeStruct) 
fResult = WinDdePostMsg /* post a DDE message to... =f 

( hwndServer /x this requesting window handle, at | 
, hwndClient had from this responding window handle, */ 
, WM_DDE_REQUEST {> a “Request” message, of 
, pDdeStruct jx as defined in this memory object, * 
, DDEPM_RETRY /% and retry if receiving queue is full.*/ 


As 
} 
return (fResult); 


/ —— 
K* 
ex FUNCLIOn : DdeRequestWarmLink 
K* 
** Usage: Requests that a permanent data-link be established with the 
aad Specified ’Server’ window, and that the ’Server’ post no data 
me in the resulting WM_DDE_DATA messages. 
K* 
BOOL /* fResult: Success indicator ch 
APIENTRY DdeRequestWarmLink 
( 
HWND hwndServer /* desired server window handle * if 
HWND hwndClient /* requesting window handle ard 
Paz psziltemName /* desired item name-string at 3 
, USHORT usFormat /* desired format =f 
) 
BOOL fResult = FALSE; 
PDDESTRUCT pDdeStruct = NULL; 
/ * 
** Creates a DDE shared memory object... 
ay 
pDdeStruct = DdeMakeDdeStruct /* create a shared memory object * f 
( pszItemName /* null (0x00) terminated ASCII string *f 
, NULL /* pointer to data (not applicable) is 
» BL /* size of data (in bytes) wf 


usFormat /* registered DDE format identifier a 
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, DDE_FNODATA /* send no data in updates at i 
| DDE_FACKREQ /* set DDE_FACKREQ status flag in ar 
1% ye Subsequent WM_DDE_DATA messages ad | 
/* 
** If shared memory object successfully created... 
ay 
if (pDdeStruct) 
{ 
fResult = WinDdePostMsg f- post @ DDE Wessage to... * | 
( hwndServer [* this requesting window handle, * f 
, hwndClient /* from this responding window handle, */ 
, WM _DDE_ADVISE ie a “UnAdvise” message, am | 
, pDdeStruct f* as defined in this memory object, * 
, DDEPM_RETRY fe and retry if receiving queue is full.*/ 


ae 
} 
return (fResult); 


/ * = SS 
*K* 
se FUNCE ON: DdeRequestHotLink 
K* 
x= Usage: Requests that a permanent data-link be established with the 
ne specified ’Server’ window, and that the ’Server’ post data 
wR in the resulting WM_DDE_DATA messages. 
K* 
=> SS SS SS SS ee ee ee ee ee SS SS SS SS SS SK / 
BOOL /* fResult: Success indicator wy 
APIENTRY DdeRequestHotLink 
( 
HWND hwndServer /* desired server window handle rs 
HWND hwndClient /* requesting window handle wy 
PSZ pszItemName /* desired item name-string * 
, USHORT usFormat /* desired format a 
) 
BOOL fResult = FALSE; 
PDDESTRUCT pDdeStruct = NULL; 
/ * 
** Creates a DDE shared memory object... 
ae 
pDdeStruct = DdeMakeDdeStruct /* create a shared memory object uid 
( pszItemName /* null (0x00) terminated ASCII string * 
» NULL /* pointer to data (not applicable) * i] 
» Ole /* size of data (in bytes) aj 
, usFormat /* registered DDE format identifier = 


, DDE_FACKREQ /* set DDE_FACKREQ status flag in * f/f 
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ie /* subsequent WM_DDE_DATA messages «i 
/* 
**x If shared memory object successfully created... 
sat J 
if (pDdeStruct) 
fResult = WinDdePostMsg /* post a DDE message to... * 
( hwndServer /* this requesting window handle, wy 
, NhwndClient {* from this responding window handle, */ 
, WM_DDE_ADVISE oe a “Advise” message, a 
, pDdeStruct es as defined in this memory object, * 
, DDEPM_RETRY /* and retry if receiving queue is full.*/ 


} 
return (fResult); 


/ kXseee eae eae SS SS SS SS SS SS SSS SS SS SS SS 5 5 $5 5 $5555 == === = 

Kx* 

** Function: DdeScanCommandString 

Kx* 

**x Usage: Extract DDE commands strings from a CF_TEXT formatted buffer. 

k* 

** Remarks: This function is similar to the C-runtime sscanf function. It 

ae reads pszBuffer, matching delimiters with pszFormat and extracts 

a tokens into a variable number of arguments. 

kx 

ial The format string is matched with the buffer as follows: 

ial following ways: 

*K* 

ne Format Buffer Action 

k* fa as a 

a Space 0 or more spaces None 

WR %S 1 or more alphabetic chars Copy to next arg (PSZ) 

ms Cl l1 or more numeric chars Copy to next arg (PULONG) 

ies Other Exact match Chars must match 

Kx 

ial pszBuffer - Buffer to be tokenized 

wn pszFormat - Format string 

we fCaseSensitive - Case sensitivity flag 

ll SPOS s<4 - Q or more ptrs to tokens to be extracted 

*x* 

Sass SSS SS SS SS SSS SSS SS SS SS SS SS SS SSS SS SS SS SS SS SS SS SSS SS SS === =* |/ 
BOOL /* fResult: Success indicator mf 


APTENTRY DdeScanCommandString 


PSZ pszBuffer 
, PaZ pszFormat 
,  BOOL fCaseSensitive 
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) 

#define FSCANNING Ox0000 
#define FTOKEN_VALID Ox0001 
#fdefine FTOKEN_INVALID 0x0002 


USHORT FfsState = FSCANNING; 
Pot pSZArg; 
PULONG pulArg; 
va_list valArgs; 


va_Start (valArgs, fCaseSensitive) ; 


/* 
ws EXTPact takens until told tO STOOD... 
mf 
while (fsState == FSCANNING) 
| 
/* 
me What should we be looking for? 
as 
Switch (*pszFormat) 
case SPACE: 
/* 
wes Expect 0 or more spaces, just skip over them... 
wy 
while (*pszBuffer == SPACE) 
pszBufter++: 
DSZFOC Ma Ls 
break; 
case “2: 
/* 
ell Expect a token, but what type? 
a J 
oszrormattt: 
switch (*pszrFormat) 
cose "Ss" 
case “3°: 
je 


bales Expect a string, is it there? 


ols 


/* 


K* 


sal 3 


/* 


*x* 


ay 


/* 


K* 


i 3 
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if (isalpha(*pszBuf fer) ) 


pszArg = va_arg( valArgs, PSZ ); 


while (isalpha(*pszBuffer) ) 


| 


*pszArg = *pszBurTfer; 
pszArgt+; 
pszBuffert+; 


null terminate string... 


*pszArg 


ei ae 


Skip to next field... 


pszFormat++; 
else 
fsState = FIOKEN_INVALID; 


break; 


Case 
Case 


gee 
Oe 


Expect a number, is it there? 


if Cisdigit(*oszBuf fer) 


pulArg 
*pulArg 


= va_arg( valArgs, PULONG ); 


0 ’ 


while (isdigit(*pszBuffer) ) 


*pulArg = (10 * *pulArg) + (ULONG)(*pszBuffer - 
pSZBUTTar+t ; 
pszFormatt ; 


else 


fsState 


FTOKEN_INVALID; 


“te 


13 


161 


162 DYNAMIC DATA EXCHANGE FOR 0S/2 PROGRAMMERS 


} 
break; 
} 
default: 
{ 
fsState = FIOKEN_INVALID; 


break; 
break; 
case ‘\0’: 
fsState = (*pszBuffer == ’\0’) 
? FTOKEN_VALID 
FTOKEN_INVALID; 
break; 
default: 
/* 
we Expect a particular delimiter, is it there? 
io | 
if ((fCaseSensitive && (*pszBuffer == *pszFormat) ) 
|| (!fCaseSensitive && (toupper(*pszBuffer) == toupper(*pszFor- 
mat)))) 
pszBuffer+t+; 
pszFormat++; 
else 
fsState = FTOKEN_INVALID; 
break; 
/* 
** Return TRUE/FALSE depending on final state. 
at i 


return (fsState == FTOKEN_VALID); 


ee FUEL ION: DdeSetPastLink 


** USage: Sets the ’Link’ format in the system clipboard. 


K* 
BOOL /* fResult: Success indicator 
APTENTRY DdeSetPasteLink 
( 
Poe pszAppName 
Poe pszlopic 
, PSZ pszIltemName 
) 
{ 
APIRET ApiRet = 0; 
BOOL fResult = FALSE; 
PVOID pvResult = NULL; 
USHORT cbResult = 0; 
USHORT cbLinkData = strlen (pszAppName) 
+ SLrlen Upsziopic) 
+ strlen (pszItemName) 
+ 4s 
CHAR szLinkFmt [] = “%S@%LS@%SQ@” ; 
PVOID pvLinkData; 
/* 
** Open system clipboard... 
* if 
fResult = WinOpenClipbrd 
( hab /* handle anchor-block 
ys 
/* 
xx If clipboard opened... 
at | 
if (fResult) 
/* 
lial Allocate shared memory object to hold clipboard format... 
a i 
ApiRet = DosAllocSharedMem 
( &pvLinkData /* address to receive memory address 
» NULL /* use unnamed shared memory 
, cbLinkData /* size of memory to allocate (in bytes) 
, PAG_COMMIT /* commit all pages 
| PAG_WRITE /* memory object is writable 
| PAG_READ /* memory object is readable 
| OBJ_GIVEABLE /* memory object can be given 
Me 
/* 
Se If shared memory object allocated... 
a | 
if (ApiRet == NO_ERROR) 
{ 
PETLE pbLinkData = (PBYTE) pvLinkData; 
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i 
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/* 
iol Expand and translate link format parameters into buffer... 
K* 
le Note: Buffer will contain tokens (’@’) that are replaced later with 
me a null (0x00) character. This (token) technique is used in 
ne order to utilize the *sprintf’ function. That is, a null 
ial Character could not be used since it would be interpreted as the 
we end-of-the format string. 
wf 
cbResult = sprintf 
( pvLinkData 
, SZLIDKFMHE 
, pszAppName 
, pDSzlopic 
, pszitemName 
); 
/* 
me Scan buffer... 
me 
while (*pbLinkData) 
/* 
od For place holder tokens and replace if found... 
af 
if (*pbLinkData == ’@’) 
*pbLinkData = °*\0’; 
pbLinkData++; 
/* 
iia) Empty the system clipboard... 
* / 
fFResult = WinEmptyClipbrd 
( hab 
ie 
/* 
kl Set the *Link’ format on the system clipboard... 
we 
fResult = WinSetClipbrdData 
( hab 
, (ULONG) pvLinkData 
, usFmtLink 


CFI_POINTER 


} 
else 
{ 
fResult = FALSE; 


/* 


Kx 
a 
/* 
kk 


= 


/* 


K* 


= 


Close system clipboard... 
WinCloseClipbrd (hab); 
Return success indicator... 


return (fResult); 
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fResult: Success indicator 


desired server window handle 
requesting window handle 


create a shared memory object 
item name-string (not applicable) 
pointer to data (not applicable) 
Size of data (in bytes) 
registered DDE format identifier 


Function: DdelTerminate 
Usage: Terminates a previously 
BOOL ;* 
APIENTRY DdeTerminate 
HWND hwndServer fs 
HWND hwndClient {>= 
BOOL fResult = FALSE; 
PDDESTRUCT pDdeStruct = NULL; 
Creates a DDE shared memory object... 
pDdeStruct = DdeMakeDdeStruct {os 
( NULL fis 
, NULL 
, OL 7% 
a, fs 
, 0 f* 


}; 


DDE status flags (not applicable) 


If shared memory object successfully created... 


if (pDdeStruct) 
fResult = WinDdePostMsg 
( hwndServer 
, hwndClient 
, WM_DDE_TERMINATE 
, pDdeStruct 
, DDEPM_RETRY 


/* 
/* 
/* 
j* 
/* 
/* 


post a DDE message To... 
this requesting window handle, 
from this responding window handle, 
a “Terminate” message, 
as defined in this memory object, 
and retry if receiving queue is full. 


my 
my 


= 
ay 
mf 
a 
sad 
a 
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i: 
} 
return (fResult); 


/ kaasaaaa aaa eee eeSSS SS SS SS SS S SS S S SS SS SS SS SS SS SS SS SS SS SS SS SS SS SS SS SS SS SES 

*K* 

ee FUNCTION: DdeTerminateLink 

K* 

*“* Usage: Terminates a previously established data-link. 

K* 

——— eS SS SS SS SS SS = K ri 
BOOL /* fResult: Success indicator * 
APTENTRY DdeTerminateLink 

( 

HWND hwndServer /* desired server window handle * i 

HWND hwndClient /* requesting window handle a i 

Pod pszItemName /* desired item name-string or 
, USHORT usFormat /* desired format ~f 
) 

BOOL fResult = FALSE; 

PDDESTRUCT pDdeStruct = NULL; 

/ * 

**k Creates a DDE shared memory object... 

a 
pDdeStruct = DdeMakeDdeStruct /* create a shared memory object mf 

( pszItemName /* null (0x00) terminated ASCII string a if 
» NULL /* pointer to data (not applicable) 
, OL /* size of data (in bytes) at J 
, usFormat /* registered DDE format identifier * 
» W /* DDE STAEUS TIBOS (HOE applicable) add 
3 

/ * 

*k If shared memory object successfully created... 

“y 
if (pDdeStruct) 

fResult = WinDdePostMsg f* post @ DDE message tO... wr 
( hwndServer fx this requesting window handle, * | 
, hwndClient ye from this responding window handle, */ 
, WM_DDE_UNADVISE be a “UnAdvise” message, “ f 
, pDdeStruct j* as defined in this memory object, * 
, DDEPM_RETRY {* and retry if receiving queue is full.*/ 


Ms 
} 
return (fResult); 
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Frequently-asked DDE Questions 


Q. Do I have to do any special coding to communicate with a DDE 
application running in a WIN-OS2 session? 


A. No. As of version 2.0, the OS/2 operating system allows DDE mes- 
sages to cross session boundaries. DDE applications can communi- 
cate with each other without regard to the session (PM or WIN-OS2) 
that it is currently executing in. The developer of a DDE application 
simply writes the application for its native environment. For exam- 
ple, if you are writing a PM client application, you code it to commu- 
nicate with a PM server application. The OS/2 operating system 
manages the exchange of DDE messages between sessions automat- 
ically. In addition, any necessary conventions in the protocol or 
standard data formats are also handled. 


Q. I have seen conflicting examples and documentation regarding the 
calculation of the cbData field of the DDESTRUCT structure. Some 
examples include the size of the DDESTRUCT structure, the length 
of the item name-string, and the size of the data portion (if any), 
while still others use only the size of the data portion. Which 
calculation is correct? 
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A. 


The cbData field contains the size of the data portion only. If no data 
is associated with the DDE message, this field will contain a value 
of zero (0). 

Much confusion and debate has existed over the correct calculation 
of this field. The source of the confusion is due, in part, to the name 
given to the field and its position in the structure. It was a common 
practice of the original OS/2 developers to define a field, in the 
beginning of a structure, that would contain the total size of the 
structure. This practice was especially prevalent in a variable-length 
memory object such as the DDESTRUCT structure. The use of such 
a field exists in the DDEINIT structure, which has also contributed 
to the confusion. 

Typically, when such a field is defined, it is given the simple 
identifier, such as cb, which in Hungarian notation means count- 
bytes or, in this case, the size of the structure in bytes. As in the case 
of cbData, the addition of the word data gives a clue to its true 
meaning. 


Should I post an acknowledgement message before or after process- 
ing the DDE transaction? 


An acknowledgement message is always posted after the receipt and 
processing of a WM_DDE_EXECUTE, WM_DDE_DATA, 
WM_DDE_ADVISE, WM_DDE_UNADVISE, or WM_DDE_POKE 
message, as well as, in some cases, aWM_DDE_REQUEST message. 


When is it OK to free any registered atom names? 
Atom name-strings, registered by an application for the purpose of 
identifying formats, can safely be deleted only after all conversations 


that involve the atom have successfully terminated. 


Can I access a DDE application running on another workstation in 
a network? 


No. DDE is a single-system message-passing protocol. 


Q. What is returned from the WinDdeRespond API? And, what is its 


significance? 


The return value from this API is the same value returned by a client 
application when processing the WM_DDE_INITIATEACK message 
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or the OS/2 operating system if an error occurred. The value is 
significant to a server application when determining the state of a 
conversation link. If a value of zero (0) is returned, then the conver- 
sation link is incomplete. Typically, a server application will wait for 
a corresponding WM_DDE_TERMINATE message from the client 
application. 


Q. When and how is the CONVCONTEXT structure used? 


A. ACONVCONTEXT structure is used to specify additional informa- 


tion regarding the DDE conversation. Both client and server appli- 
cations should include a CONVCONTEXT structure in both the 
WM_DDE_INITIATEACK and WM_DDE_INITIATE messages re- 
spectively. The contents of the CONVCONTEXT structure are used 
to compare application, topic, item, and command strings only. 


. Can I include data in the data portion of a DDESTRUCT structure 
when posting a WM_DDE_REQUEST or WM_DDE_ADVISE mes- 
sage? 


. Technically, there is nothing preventing you from including data in 


the data portion of these messages. However, the protocol does not 
specify how this data should be interpreted. Moreover, the imple- 
mentation of the DDE protocol in the Windows environment does not 
provide for the inclusion of data with these messages. Subsequently, 
the component of the OS/2 operating system responsible for Dynamic 
Data Exchange between OS/2 and WIN-OS2 sessions, ignores the 
contents of this field when exchanging messages. 


Q. Do I need to support the System topic in my server application? 


A. Itis not required that a server application support the System topic. 


However, it is highly recommended and suggested that it does. 


. Who is responsible for freeing the memory object associated with a 
DDE message? 


. The application receiving the message is responsible for freeing the 


memory object once it has received the message. This may be done 
explicitly by issuing a DosFreeMem API against the memory object 
address, or implicitly by reusing the memory object for the response 
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Q. 


and issuing a WinDdePostMsg API without the DDEPM_NOFREE 
flag set. 


Note: Fora WM_DDE_INITIATE and WM_DDE_INITIATEACK 
message, the receiving application must explicitly free the memory 


Why should I need to provide a unique window handle for each 
conversation? 


A. Several reasons exist for providing unique window handles: 


# An application can identify a particular conversation link 


simply by the window handle (in PM, a window handle is 
guaranteed to be unique). 

Standard PM API calls can be used to maintain and control 
conversation links (e.g., WinEnumerateWindow). This 
frees an application developer from having to develop a 
special structure to maintain this information, such as 
linked lists. 


= A window can contain instance data; that is, information can 


be kept in a window on a per-window (or in this case a 
per-conversation) basis. This simplifies the programming 
logic of multiple conversations. Typically, developers create 
these windows as invisible since their main purpose is to 
handle a DDE conversation link rather than display infor- 
mation. 
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For millions of OS/2 and Windows programmers, achieving application communication 
within the system is a critical goal. Finding ways to incorporate dynamic data exchange 
to maximize operating system efficiency has been a difficult—and often frustrating— 
feat. 


Until now, Dynamic Data Exchange for OS/2 Programmers offers a complete, single- 
source guide to dynamic data exchange (DDE) and its protocol for developing DDE 
applications. : 


Beginning with a brief overview of DDE for less technical readers, the book then pro- 
vides in-depth coverage of every area of DDE concepts and protocol—including data 
items and formats, transactions, guidelines for initiation—and comes with two complete 
working DDE applications with supporting example code. 


You can’t find a more comprehensive collection of invaluable DDE information in 
manufacturer documentation or programming examples. Dynamic Data Exchange for 
OS/2 Programmers offers: 


¢ The definitive definition of the DDE protocol with examples for OS/2 and Windows, 
and a brief discussion of “Hungarian” notation 

¢ A complete listing of the differences and similarities between OS/2 and Windows 
implementations 

¢ Details on Inter-application data exchange and unsolicited updates, and how to sim- 
plify the programming logic of multiple “conversations” 

¢ Step-by-step programming guides for a successful implementation of DDE 
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